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Introductory Remarks 


Purpose of This Document 

This L4 Reference Manual serves as defining document for all L4 APIs and ABIs. Primarily, it addresses L4 microkernel 
implementors as API/ABI suppliers and code-generator or library implementors as API/ABI users. The reference manual 
assumes intimate knowledge of basic L4 concepts and hardware architecture. Its key point is precise definition, not 
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Understanding This Document 


This L4 Reference Manual defines the generic API for all 32-bit and 64-bit machines. As such, the generic reference 
manual is independent of specific processor architectures. It is complemented by processor-specific ABI specifications. 
Some of them can be found in the appendix of this document. 

In this document, we differentiate between Logical Interface, Generic Binary Inteiface, Generic Programming Inter- 
face, Convenience Programming Interface and Processor-specific Binary Inteiface. 


Logical Interface The logical inteiface defines all concepts and logical objects such as system-call operations, 
logical data objects, data types and their semantics. Altogether, they form the logical L4 API. 


Generic Binary Interface 

Binary representations of most data types and generic data objects are defined independently of 
specific processors (although there are two different versions, one for 32-bit and a second one 
for 64-bit processors). Both versions together form the generic binary interface of L4. 

From a purist point of view, logical interface plus generic binary interface could be regarded as a complete specification of 
the hardware-independent L4 microkernel interface. However, for ease-of-use and standardization reasons, the mentioned 
two fundamental interfaces are complemented by two more interface classes: 


Generic Programming Interface 

The generic programming interface defines the objects of the logical interface and the generic 
binary interface as pseudo C++ classes. The language bindings for regular C is for the most part 
identical to C++. For the cases where the C language causes function naming conflicts, the C 
version of the function name is given in brackets. 

For the time being, only the C and C++ versions of the API are specified. The concrete syntax 
of other language interfaces will be left open. Later on, all language bindings will be included 
in the generic programming interface. 


Convenience Programming Interface 

This interface is not part of the L4 microkernel specification in the strict sense. All of its data 
types and procedures can be implemented using the generic programming interface. Strictly 
speaking, it is an interface on top of the microkernel that makes the most common operations 
more easily usable for the programmer. 

It is important to understand that convenience and ease-of-use, not completeness, is the criterion 
for this interface. The convenience programming interface supports programmers by offering 
operations that together cover about 95% of the required microkernel functionality. For the 
remaining 5%, the programmer has to use the basic (not so convenient) operations of the generic 
programming interface. 

Obviously, the convenience programming interface is not mandatory. Consequently, from a 
minimalist point of view, there is no need to include it in the generic L4 specification. 

Nevertheless, for reasons of standardization and thus portability of software, every 
complete L4 language binding has to include the entire convenience programming 
interface. 

Implementation remark: Although the convenience interface can be completely implemented 
on top of the generic programming interface, i.e., processor independently, the implementor 
of the convenience interface may implement it hardware-dependently and thus incorporate any 
optimization that becomes possible through a specific processor-specific binary interface. 

The last interface class is not part of the generic L4 API specification. 


Processor-specific Binary Interface 

Defines the processor-specific binary interface. 
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Notation 


Basic Data Types 

This reference manual describes the L4 API and ABI for both 32-bit and 64-bit processors. The data type Word denotes 
a 32-bit unsigned integer on a 32-bit processor and a 64-bit unsigned integer on a 64-bit processor. Word64, Word32 and 
Wordl6 denote 64, 32, and 16-bit words independent of the processor type. 


Privileged Threads 

Some system calls can only be executed by privileged threads. Any thread belonging to the same address space as one of 
the initial threads created by the kernel upon boot-time (see page 84) are treated as privileged. 


Bit Fields 

Bit-field lengths are denoted as subscripts u where i relates to a 32-bit processor and j to a 64-bit processor. Bit-field 
subscripts (,) specify bit fields that have the same size for both 32-bit and 64-bit processors. Byte offsets are given as 
±i / ± j for 32-bit and 64-bit processors. If all bit-fields of a specified word only adds up to 32 bits, the remaining upper 
32 bits on 64-bit processors are undefined or ignored. 


Undefined, Ignored, and Unchanged 


Output parameters or bit fields can be undefined. Corresponding parameters or fields are denoted 
by ~. They have no defined value on output, i.e., they may have any value or may even be 
unaccessible. Any algorithm relying on the value of undefined parameters or bit fields is defined 
to be incorrect. 


Input parameters or bit fields can be specified as ignored , denoted by -. Such parameters or fields 
can hold any value without affecting the invoked service. - is also used to define bit fields that 
are available for additional information. For example, fpage denotations contain some ignored 
bits that are used for access control bits in some system calls. 


In processor-specific interfaces, registers are sometimes defined to be unchanged. This is de- 
noted by =. 


Upward Compatibility 

The following holds for future API versions and sub-versions that are specified as upward-compatible to the current 
version. 


Output parameters and bitfields. 

Fields currently defined as undefined (~) may be specified as defined. Such newly defined fields 
will only deliver additional information. They can be ignored if the system call is used exactly 
like specified in the current API. 


Input parameters and bit fields. 

Fields currently defined as ignored (-) may be specified as defined. However, the content of such 
fields will be only relevant for newly defined features. Such fields will be ignored if a system 
call is used with the “old” semantics specified in this API. 
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Using the API 


Naming 

A programmer can use all function, type, and constant definitions defined in the generic and convenience programming 
interfaces throughout this manual. All definitions must, however, be prefixed with the string “L4_” and type names 
must contain the “_t” suffix (e.g., use “L4_Ipc ()” and “L4_MsgTag _t” rather than “Ipc ()” and “MsgTag”). The interfaces 
are currently only defined for C++ and C. In some cases the naming used for function names causes conflicts in the C 
language. These conflicts must be resolved using the alternative name specified in brackets after the function definition. 


Include Files 

The relevant include files containing the required definitions and declarations are specified in the beginning of the generic 
and convenience interface sections. In general there is one include file for each chapter in the manual. If only the basic 
L4 data types are needed they can be included using <14/types.h>. 
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Revision History 


Revision 1 

Intial revision. 


Revision 2 

- Clarified the specification of the kernel-interface page and kernel configuration page magic. 

- UntypedWords and Stringltems Acceptor constants collided with function UntypedWords(MsgTag) and Strin- 
gltems(MsgTag) function declaration. Renamed to UntypedWordsAcceptor and StringltemsAcceptor. 

- Changed kernel ids for L4Ka kernels. 

- Fixed return types for operators on the Time type. 

- Changed wrx access rights in fpages to rwx. Also changed WRX reference bits in fpages returned from UNMAP 
system call to RWX. 

- Renamed Put functions operating on MsgBuffer to Append. 

- Address space deletion is now performed by deleting the last thread of an AS. This makes creation and deletion 
symmetrical (via ThreadControl). Before, all threads but the last were deleted by ThreadControl, and the last by 
SpaceControl. 

- Added functions for creating ThreadIDs and for retrieving version and thread numbers from them. Fixed size of 
MyLocalld and MyGloballd TCRs . 

- Specified that the first three thread version numbers available for user threads are dedicated to cto, 01 , and root task 
respectively. 

- Changed the encoding of /r in the magic field of the KIP back to 0xE6 to be compatible with previous versions of the 
kernel. 

- Changed memory descriptors (e.g., dedicated memory) in the kernel-interface page and kernel configuration page to 
use an array of typed descriptors instead of a static number of predefined ones. 

- Added an appendix for the PowerPC interface. 

- Added Niltag MsgTag constant. 

- Decreased size of MsgBuffer structure to 32. 

- Changed single Fpage& argument of UnrnapO and Flush!) into pass by value. 

- Changed the ia32 kernel feature string “small” to “smallspaces”. 

- Added appendix for the ia64 interface. 

- Changed the ia32 IPC and LIPC ABI to be better suitable for common hardware featuring sysenter/sysexit and gcc. 

- Added ProcDesc convenience functions. 

- Specified which include files to use for the various parts of the API. 

- Allow privileged threads to access ia32 Model-Specific Registers. 

- Changed the ia64 ABI for system-call links and the IPC and LlPC system-calls. 

- The UTCB location of a new thread is now explicitly specified by a parameter to the ThreadControl system-call. 

- Added C versions of conflicting function names. 
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- Added a number of convenience functions for fpages, map items, grant items, string items and kernel interface page 
fields. 

- Added description of the send base in map and grant items. 

- Changed subversion numbering for Version X.2 and Version 4 API. 

- Renamed the XferTimeout TCR to XferTimeouts and split into separate send and receive timeouts. 

- Added two thread specific words to each the architecture specific TCR sections. These words are free to be used by, 
e.g., IDL compilers. 

- Changed name of L4Ka kernels to the official name. Added L4Ka:: Strawberry. 

- Added appendices for Alpha and MIPS64. 


Revision 3 

- Clarified description of the supplier field in the kernel-interface page. 

- Added NumMemoryDescriptors() convenience function. 

- Clarified the return value of Memory DescType() function. 

- Fixed faulty specification of Wait_Timeout() and ReplyWait_Timeout(). 

- Added a new h-Q ag to control parameter in the ExchangeRegisters system-call. The h- flag controls whether the 
resume/halt flag should be ignored or not. 

- Changed parameter type of TimePeriodQ from “int” to “Word64”. 

- Fixed typo in specification of the MsgTag input/output IPC parameter. 

- Added comment to IPC system-call about the read-once semantics of message registers. 

- Added member name “raw” to all L4 types declared as structs. 

- Renamed start() and stop!) functions to Start() and Stop(). 

- Describe semantics of undefined UTCB memory regions. 

- The first 10 message registers on PowerPC are now defined as backed by physical registers. 

- The first 9 message registers on Alpha are now defined as backed by physical registers. 

- Fixed MR o register allocation for IA32 syscalls and adapted syscalls accordingly. 


Revision 4 

- Added appendix for AMD64. 

- Changed MIPS64 IPC ABI to include 9 message registers. 

- Added SystemClock syscall for MIPS64. 

- Clarified the fact that an interrupt thread may be the originator thread during IPC propagation. 

- Added appendix for SPARC v9. 

- The high field of memory descriptors now specify the last addressable byte in the memory region. 
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Revision 5 

- The ErrorCode TCR is now a generic placeholder for error descriptions of failed system-calls. 

- MemoryControl now returns a result parameter. 

- Defined error codes for various system-calls (ExchangeRegisters, ThreadControl SCHEDULE SpaceCon- 
trol ProcessorControl and MemoryControl). 

- Defined convenience definitons for error code values. 

- Changed the IA32 SystemClock ABI to clobber the EDI register. 

- Specify that the KIP area and the UTCB area of an address space must not overlap. 

- For the PowerPC system call trap exception IPC, use a message label of -5, and preserve register LR. 

- The ExchangeRegisters system-call can no longer activate an inactive thread. 

- The Fpage argument to Set_Rights() is now passed by reference. 

- Fixed inconsistencies about the number of available buffer registers. 

- Renamed Void to void. Char to char, and bool to Bool. 

- The Start() convenience function now aborts any ongoing IPC operations. 

- The UnrnapO and Flush() convenience functions operating on a single fpage now deliver the status bits of the modified 
fpage. 

- MIPS64 now uses the kO ($26) register for holding the UTCB address. 

- Added two new memory types for MEMORYCONTROL on MIPS64. 

- Added appendix for generic Bootlnfo. 

- Make it clear that it is not possible to activate a thread in an address space which has not been properly configured 
with SPACECONTROL 

- Added appendix for ARM. 

- If using a 64 bit kernel, define second 32 bit word of kernel interface page to 0. 

- Changed the ABI for the PowerPC system calls UNMAP and MemoryControl . 
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KERNEL INTERFACE PAGE 


1.1 Kernel Interface Page [Data Structure] 


The kernel-interface page contains API and kernel version data, system descriptors including memory descriptors, and 
system-call links. The remainder of the page is undefined. 

The page is a microkernel object. It is directly mapped through the microkernel into each address space upon address- 
space creation. It is not mapped by a pager, can not be mapped or granted to another address space and can not be 
unmapped. The creator of a new address space can specify the address where the kernel interface page has to be mapped. 
This address will remain constant through the lifetime of that address space. Any thread can obtain the address of the 
kernel interface page through the KERNELlNTERFACE system call (see page 7). 


KernDescPtr 


ProcDescPtr 


MemDescPtr 

+F0/+1E0 
+E0/+1C0 
+D0/+1A0 
+C0/+180 
+B0/+160 
+A0/+140 
+90/ +120 
+80/ +100 
+70/ +E0 
+60/ +C0 
+50/ +A0 
+40/ +80 
+30/ +60 
+20/ +40 
+ 10 / +20 
+0 


L4 version parts 


Supplier 

KernelVer 

KemelGenDate 

Kernelld 




InternalFreq 

ExternalFreq 


MemoryDesc 



Schedule SC 

ThreadSwitch SC 

SystemClock SC 

ExchangeRegisters SC 

Unmap SC 

LlPC SC 

Ipc sc 

MemoryControl pSC 

ProcessorControl pSC 

ThreadControl pSC 

SpaceControl pSC 

Processorlnfo 

Pagelnfo 

Threadlnfo 

Clocklnfo 

ProcDescPtr 

Bootlnfo 


KipArealnfo 

Utcblnfo 







Memorylnfo 






KernDescPtr 

API Flags 

API Version 

0(0/32) 'K’ 230 '4' ’L' 


+C/+18 


+ 8/ +10 


+4/ +8 


+0 
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Note that this kernel interface page is basically upward compatible to the kernel info page of versions 2 and X.O. The 
magic byte string “L4/iK” at the beginning of the object identifies the kernel interface page. 

Version/id number convention: Version/subversion/subsubversion numbers and id/subid numbers with the most signif- 
icant bit 0 denote official versions/ids and are globally unique through all suppliers. Version/id numbers that have the 
most significant bit set to 1 denote experimental versions/ids and may be unique only in the context of a supplier. 


API Description 


API Version 


API Flags 


ee 


ww 


version (g) 


subversion 


( 16 ) 


version 

subversion 


0x02 


Version 2 

0x83 

0x80 

Experimental Version X.O 

0x83 

0x81 

Experimental Version X. 1 

0x84 

rev 

Experimental Version X.2 (Revision rev ) 

0x04 

rev 

Version 4 (Revision rev) 


( 28 / 60 ) 


WW 


ee 


= 00 : little endian, 

= 01 : big endian. 

= 00 : 32-bit API, 

= 01 : 64-bit API. 

Note that this field can not be used directly to differentiate between little endian and big endian 
mode since the ee field resides in different bytes for both modes. Furthermore, the offset address 
of the API Flags is different for 32-bit and 64-bit modes. In summary, a direct inspection of the 
kernel interface page is not sufficient to securely differentiate between 32/64-bit modes and 
little/big endian modes. 

Secure mode detection is enabled through the KERNELlNTERFACE system call (see page 7). It 
delivers the API Flags in a register. 


System Description 


Processorlnfo 


S (4) 


( 12 / 44 ) 


processors — 1 


The size of the area occupied by a single processor description is 2 s . Location of description 
fields for the first processor is denoted by ProcDescPtr. Description fields for subsequent pro- 
cessors are located directly following the previous one. 


processors 

Number of available system processors. 


Pagelnfo 


page-size mask (22 /54) 


(7) 


rwx 


page-size mask 

If bit k — 10 of the page-size mask field (bit k of the entire word) is set to 1 hardware and kernel 
support pages of size 2 fc . If the bit is 0 hardware and/or kernel do not support pages of size 2 k . 
Note that fpages of size 2 k can be used, even if 2 k is no supported hardware page size. Infor- 
mation about supported hardware page sizes is only a performance hint. 

rwx Identifies the supported access rights (read, write, execute ) that can be set independently of 
other access rights. A 1-bit signals that the right can be set and reset on a mapped page. For 
rwx = 010. only write permission could be controlled orthogonally. The processor would 
implicitly permit read and execute access on any mapped page. For rwx =111, all three rights 
could be set and reset independently. 
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Threadlnfo 


i Number of valid thread-number bits. The thread number field may be larger but only bits 

0 ... t — 1 are significant for this kernel. Higher bits must all be 0. 

U serBase 

Lowest thread number available for user threads (see page 14). The first three thread numbers 
will be used for the initial thread of cro, ci, and root task respectively (see page 84). The version 
numbers (see page 14) for these initial threads will equal to one. 

SystemBase 

Lowest thread number used for system threads (see page 14). Thread numbers below this value 
denote hardware interrupts. 

Clocklnfo 


ReadPrecision 

Specifies the minimal time difference ^ 0 that can be detected by reading the system clock 
through the SystemClock system call. Basically, this is the precision of the system clock 
when reading it. 

Schedule Precision 

Specifies the maximal jitter (±) for a scheduled thread activation based on a wakeup time (pro- 
vided that no thread of higher or equal priority is active and timer interrupts are enabled). 
Precisions are given as time periods (see page 28). 

Utcblnfo 

s The minimal area size for an address space’s UTCB area is 2 s . The size of the UTCB area limits 

the total number of threads k to 2 a mk < 2 s . 

m UTCB size multiplier. 

a The UTCB location must be aligned to 2°. The total size required for one UTCB is 2 “to. 

KipArealnfo 


Bootlnfo Prior to kernel initialization a boot loader can write an arbitrary value into the Bootlnfo field of 

the kernel configuration page (see page 84). Post-initialization code, e.g.. a root server can later 
read the field from the kernel interface page. Its value is neither changed nor interpreted by the 
kernel. This is a generic method for passing system information across kernel initialization. 


Processor Description 


ProcDescPtr Points to an array containing a description for each system processor. The Processorlnfo field 
contains the dimension of the array. ProcDescPtr is given as an address relative to the kernel 
interface page’s base address. 

ExternalFreq External Bus frequency in kHz. 

IntemalFreq Internal processor frequency in kHz. 



The size of the kernel interface page area is 2 s . 





Kernel Description 
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KemDescPtr Points to a region that contains 4 kernel-version words (see below) followed by a number of 
O-terminated plaintext strings. The first plaintext string identifies the current kernel followed by 
further optional kernel-specific versioning information. The remaining plaintext strings identify 
architecture dependent kernel features (see Appendix A.3). A zero length string (i.e., a string 
containing only a O-character) terminates the list of feature descriptions. 

KernelDescPtr is given as an address relative to the kernel interface page’s base address. 


Kernelld 


id (g) 


subid (g) 


(16) 


Can be used to identify the microkernel. 


id 

subid 

kernel 

supplier 

0 

1 

L4/486 

GMD 

0 

2 

L4/Pentium 

IBM 

0 

3 

L4/x86 

UKa 

1 

1 

L4/Mips 

UNSW 

2 

1 

L4/ Alpha 

TUD, UNSW 

3 

1 

Fiasco 

TUD 

4 

1 

L4Ka::Hazelnut 

UKa 

4 

2 

L4Ka::Pistachio 

UKa 

4 

3 

L4Ka: :Strawberry 

UKa 


KernelGenDate 


~ (16/48) 

year-2000 

month (4) 

day (5) 


Kernel generation date. 


KernelVer 


Supplier 


ver (8) 


subver ^ 


subsubver 


Can be used to identify the microkernel version. Note that this kernel version is not necessarily 
related to the API version. 


The four least significant bytes of the supplier field specify a character string identifying the 
kernel supplier: 


“GMD„ ” 
“IBM,, ” 
“UNSW” 
“TUD„ ” 
“UKa„ ” 


GMD 

IBM Research 

University of New South Wales, Sydney 
Technische Universitat Dresden 
Universitat Karlsruhe (TH) 


System-Call Links 

SC Link for normal system call. 

pSC Link for privileged system call, i.e., a system call that can only be performed by a privileged 

thread. 

The system-call links specify how the application can invoke system-calls for the current micro- 
kernel. The interpretation of the system-call links is ABI specific, but will typically be addresses 
relative to the kernel interface page’s base address where kernel provided system-call stubs are 
located. 


Memory Description 


Memorylnfo 


MemDescPtr (i 6 /32) 


n (16/32) 
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KERNEL INTERFACE PAGE 


MemDescPtr 

Location of first memory descriptor (as an offset relative to the kernel-interface page's base 
address). Subsequent memory descriptors are located directly following the first one. For mem- 
ory descriptors that specify overlapping memory regions, later descriptors take precedence over 
earlier ones. 

n Number of memory descriptors. 


MemoryDesc 


high/ 2 10 ( 22 / 54 ) 

~ ( 10 ) 

low/ 2 10 ( 22 / 54 ) 

V 


t ( 4 ) 

type (4) 


+4/ +8 
+0 


high Address of last byte in memory region. The ten least significant address bits are all hardwired 
to 1. 

low Address of first byte in memory region. The ten least significant address bits are all hardwired 

to 0. 

v Indicates whether memory descriptor refers to physical memory (w = 0) or virtual memory 

(v = 1). 

type Identifies the type of the memory descriptor. 


Type 

Description 

0x0 

Undefined 

0x1 

Conventional memory 

0x2 

Reserved memory (i.e., reserved by kernel) 

0x3 

Dedicated memory (i.e., memory not available to user) 

0x4 

Shared memory (i.e., available to all users) 

OxE 

Defined by boot loader 

OxF 

Architecture dependent 


t, type = OxE 

The type of the memory descriptor is dependent on the bootloader. The t field specifies the exact 
semantics. Refer to boot loader specification for more info. 

t, type = OxF 

The type of the memory descriptor is architecture dependent. The t field specifies the exact 
semantics. Refer to architecture specific part for more info (see page 115). 

t, type ¥= OxE, type # OxF 

The type of the memory descriptor is solely defined by the type field. The content of the t field 
is undefined. 
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1.2 KernelInterface [Slow Systemcall] 

> void* kernel interface page 

Word API Version 
Word API Flags 
Word Kernelld 


Delivers base address of the kernel interface page, API version, and API flags. The latter two values are copies of the 
corresponding fields in the kernel interface page. The API information is delivered in registers through this system call (a) 
to enable unrestricted structural changes of the kernel interface page in future versions, and (b) to enable secure detection 
of the kernel’s endian mode (little/big) and word width (32/64). 

The structure of the kernel interface page is described on page 2. The page is a microkernel object. It is directly 
mapped through the microkernel into each address space upon address-space creation. It is not mapped by a pager, can 
not be mapped or granted to another address space and can not be unmapped. The creator of a new address space can 
specify the address where the kernel interface page has to be mapped. This address will remain constant through the 
lifetime of that address space. 

Any thread can determine the address of the kernel interface page through this system call. Since the system call may 
be slow it is highly recommended to store the address in a static variable for further use. 

It is also possible to use a unique address for the kernel interface page in all address spaces of a (sub)system. Then, 
the kernel interface page can be accessed by fixed absolute addresses without using the current system call. 

Besides other things, the page describes the current API. ABI, and microkernel version so that a server or an application 
can find out whether and how it can run on the current microkernel. Since the kernel interface page also contains API- 
and ABI-specific data for most other system calls the page’s base address is typically required before any other system 
call can be used. 

To enable version detection independently of the API and ABI, the current system call is guaranteed to work in all L4 
versions. The systemcall code will never change and will be the same on compatible processors. (If a processor is upward 
compatible to multiple incompatible processors the kernel should offer multiple systemcall codes for this function.) 


Output Parameters 


kernel interface page 


VerX.l and above 


Kernel interface page address, always page aligned. 0 is no valid address. 

VerX.O and below 


Older versions (2, X.O, etc.) do not include the kernel interface page as a kernel mapped page. 
No address is delivered. 


API Version 


see page 3, “Kernel Interface Page” 


API Flags 






see page 3, “Kernel Interface Page' 







KERNELINTERFACE 


Kern ell d 


id (8) 


subid (8) 


( 16 ) 


see page 5, “Kernel Interface Page” 


No pagefaults will happen. 


Pagefaults 


Generic Programming Interface 

System-Call Function: 

#include <l4/kip.h> 

void * Kernellnterface (Word& ApiVersion, ApiFlags, Kernelld) 


Convenience Programming Interface 

Derived Functions: 

#include <l4/kip.h> 

struct MemoryDesc {Word raw [2]} 
struct ProcDesc { Word raw [4] } 

void* Kernellnterface () [GetKernellnterface] 

Delivers a pointer to the kernel interface page. 

Word ApiVersion () 

Word ApiFlags () 

Word Kernelld () 

void KernelGenDate ( void * Kernellnteiface, Word& year, month, day) 

Word KernelVersion ( void * Kernellnteiface) 

Word KernelSupplier (void* Kernellnterface) 

Delivers the API Version/ API Flags/Kernel Id/kernel generation date/kemel version/kernel sup- 
plier. 

Word NumProcessors (void* Kernellnteiface) 

Word NumMemoryDescriptors (void* Kernellnteiface) 

Delivers number of processors in the system/number of memory descriptors in the kernel- 
interface page. 

Word PageSizeMask (void* Kernellnterface) 

Word PageRights (void* Kernellnteiface) 

Delivers supported page sizes/page rights for the current kernel/hardware architecture. 

Word ThreadldBits (void* Kernellnterface) 

Word ThreadldSystemBase (void* Kernellnteiface) 




KERNELINTERFACE 


9 


Word ThreadldUserBase ( void * Kernellnterface) 

Delivers number of valid bits for thread numbers/lowest thread number for system threads/lowest 
thread number for user threads. 

Word ReadPrecision (void* Kernellnterface) 

Word SchedulePrecision (void* Kernellnterface) 

Delivers the SystemClock read precision/maximal jitter for wakeups (both in /rs). 

Word \JtcbAreaSizeLog2 (void* Kernellnterface) 

Word UtcbAlignmentLog2 (void* Kernellnterface) 

Word UtcbSize (void* Kernellnterface) 

Delivers required minimum size of UTCB area/alignment requirement for UTCBs/size of a sin- 
gle UTCB. 

Word KipAreaSizeLog2 (void* Kernellnterface) 

Delivers size of kernel interface page area. 

Word Bootlnfo (void* Kernellnterface) 

Delivers the contents of the boot info field. 

char* KernelVersionString (void* Kernellnterface) 

Delivers the kernel version string. 

char* Feature (void* Kernellnterface, Word num) 

Delivers the numth kernel feature string, or a null pointer if num exceeds the number of avail- 
able feature strings. 

MemoryDesc* MemoryDesc (void* Kernellnterface, Word num) 

Delivers the numth memory descriptor, or a null pointer if num exceeds the number of available 
descriptors. 

ProcDesc* ProcDesc (void* Kernellnterface, Word num) 

Delivers the numth processor descriptor, or a null pointer if num exceeds the number of pro- 
cessors of the system (see Processorlnfo). 


Support Functions: 

#include <l4/kip.h> 

Word UndefinedMemoryType 

Word CoiiventionalMemoryType 

Word ReservedMemoryType 

Word DedicatedMemoryType 

Word SharedMemoryType 

Word BootLoaderSpecificMemoryType 

Word ArchitectureSpecificMemoryType 


Bool IsVirtual (MemoryDesc& m) [ IsMemoryDescVirtual \ 

Delivers true if memory descriptor specifies a virtual memory region. 


Word Type (MemoryDesc& m) 

Word Low (MemoiyDesc& m) 

Word Fligh (MemoryDesc& m) 

Delivers type (t*16 + type), low limit, and high limit of memory region. 


[. MemoiyDescType \ 
[MemoryDescLow] 
[ MemoiyDescHigh ] 
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Word ExternalFreq ( ProcDesc& p) [ ProcDescExternalFreq ] 

Word InternalFreq (ProcDesc& p) [ ProcDescInternalFreq ] 

Delivers external frequency/internal frequency of processor. 
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1.3 Virtual Registers [Virtual Registers] 


Virtual registers are implemented by the microkernel. They offer a fast interface to exchange data between the microkernel 
and user threads. Virtual registers are registers in the sense that they are static per-thread objects. Dependent on the 
specific processor type, they can be mapped to hardware registers or to memory locations. Mixtures, some virtual registers 
to hardware registers, some to memory are also possible. The ABI for virtual-register access depends on the specific 
processor type and on the virtual-register type, see Appendices A.l, B.l and C.l for specific hardware details. 

There are three classes of virtual registers: 

• Thread Control Registers (TCRs), see page 16 

• Message Registers (MRs), see page 46 

• Buffer Registers (BRs), see page 57 

Loading illegal values into virtual registers, overwriting read-only virtual registers, or accessing virtual registers of other 
threads in the same address space (which may be physically possible if some are mapped to memory locations) is illegal 
and can have undefined effects on all threads of the current address space. However, since virtual registers can not 
be accessed across address spaces, they are safe from the kernel’s point of view: Illegal accesses can like any other 
programming bug only compromise the originator’s address space. 

Remark • In general, virtual registers can only be addressed directly, not indirectly through pointers. 

The generic API therefore offers no operations for indirect virtual-register access. However, 
processor-specific code generators might use indirect access techniques if the ABI permits it. 


Generic Programming Interface 

#include <l4/message.h> 

void StoreMR ( int i, Word& w) 
void LoadMR (int i, Word w) 

Delivers/sets MR i . 

void StoreMRs (int iff, Word& [k] w) 

void LoadMRs ( intiff , Word& [k] w) 

Stores/loads MR, ..i+t_i to/from memory. 

void StoreBR (int i, Word& w) 
void LoadBR (int i, Word w) 

Delivers/sets the value of BR j. 

void StoreBRs (inti, k, Word& [k]) 

void LoadBRs (inti, k, Word& [ k ]) 

Stores/loads BRi...i+fe_i to/from memory. 
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2.1 Threadld [Data Type] 


Thread IDs identify threads and hardware interrupts. A thread ID can be global or local. Global thread IDs are unique 
through the entire system. They identify threads independently of the address space in which they are used. Local thread 
IDs exist per address space; the scope of a thread’s local ID is only the thread’s own address space. In different address 
spaces, the same local thread ID may identify different and unrelated threads. 

Note that any thread has a global and a local thread ID. Both global and local thread IDs are encoded in a single word. 


Global Thread ID 

A global thread ID consists of a word, where 18 bits (32-bit processor) or 32 bits (64-bit processor) determine the thread 
number and 14 bits (32-bit processor) or 32 bits (64-bit processor) are available for a version number. At least one of the 
lowermost 6 version bits must be 1 to differentiate a global from a local thread ID. 

User-thread numbers can be freely allocated within the interval [UserBase , 2*), where t denotes the upper limit of 
thread IDs. The thread-number interval [SystemBase , UserBase ) is reserved for L4-internal threads. Hardware interrupts 
are regarded as hardware-implemented threads. Consequently, they are identified by thread IDs. Their corresponding 
thread numbers are within the interval [0 , SystemBase). The values SystemBase, UserBase, and t are published in the 
kernel interface page (see page 4). 


global thread ID 


global interrupt ID 


thread no (i 8 / 32 ) 

versionj 14 / 32 ) (mod 64) 


intrno (i 8 / 32 ) 

1 (14/32) 


Global thread IDs have a version field whose content can be freely set by those threads that can create and delete threads. 
However, the lowermost 6 bits of the version must not all be 0, i.e. v mod 64 # 0 must hold for every version v. For 
hardware interrupts, the version field is always 1. 

The microkernel checks version fields whenever a thread is accessed through its global thread ID. However, the se- 
mantics of the version field are not defined by the microkernel. OS personalities are free to use this field for any purpose. 
For example, they may use it to make thread IDs unique in time. 


Local Thread ID 

Local thread IDs identify threads within the same address space. They are identified by the 6 lowermost bits being 0. 


local thread ID 


local id/64 (2 ©/58) 


000000 


Special Thread IDs 

Special IDs exist for nilthread and two wild cards. The thread ID anythread matches with any given thread ID, including 
all interrupt IDs. The ID anylocalthread matches all threads that reside in the same address space. 


nilthread 


anythread 


anylocalthread 
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Generic Programming Interface 


#include <l4/thread.h> 
struct ThreadId { Word raw } 


Threadld nilthread 
ThreadId anythread 
ThreadId anylocalthread 


ThreadId Globalld ( Word threadno, version ) 

Delivers a thread ID with indicated thread and version number. 

Word Version (ThreadId t) 

Word ThreadNo ( ThreadId t) 

Delivers version/thread number of indicated global thread ID. 


Convenience Programming Interface 

#include <l4/thread.h> 

Bool == (ThreadId I, r) [IsThreadEquaI\ 

Bool ! = (ThreadId l, r) [IsThreadNotEqual\ 

Check if thread IDs match or differ. The result of comparing a local ID with a global ID will 
always indicate a mismatch, even if the IDs refer to the same thread. 

Bool SameThreads ( ThreadId I, r) 

{ Globalld (1) == Globalld (r) } 

Check if thread IDs refer to the same thread. Also works if one ID is local and the other is 
global. 

Bool IsNilThread (ThreadId t) 

{ t == nilthread } 

Bool IsLocalld (ThreadId t) 

Bool IsGloballd ( ThreadId t) 

Check if thread ID is a local/global one. 

ThreadId Localld ( ThreadId t) [LocalldOf] 

ThreadId Globalld (ThreadId t) [ GloballdOf] 

Delivers the local/global ID of the specified local thread. Specifying a non-local thread delivers 
nilthread (see ExchangeRegisters, page 18). 

ThreadId MyLocalhl () 

ThreadId MyGloballd () 

Delivers the local/global ID of the currently running thread (see TCRs, page 16). 

ThreadId Myself () 

{ MyGloballd () } 
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2.2 Thread Control Registers (TCRs) [Virtual Registers] 


TCRs are a fast mechanism to exchange relatively static control information between user thread and microkernel. TCRs 
are static non-transient per- thread registers. 


VirtualSender/ActualSender (32 /64) 


IntendedReceiver (32/64) 


XferTimeouts (32/64) 


ErrorCode (32/64) 


Preempt Flags ( 8 ) 


Cop Flags ( 8 ) 


ExceptionHandler (32/64) 


Pager ( 32 /64) 


UserDefinedHandle (32/64) 


ProcessorNo (32/64) 


MyLocalld (32 /64) 


MyGloballd (32 / 64 ) 


R/W 

see IPC 

i?.-only 

see IPC 

R/W 

see IPC 

R-only 

see system-calls 

R/W 

see Scheduling 

W -only 

see Miscellaneous 

R/W 

see Miscellaneous 

R/W 

see Protocols 

R/W 

see Threads 

/Y-only 

see Miscellaneous 

/t'-only 

see Threads, IPC 

i?.-only 

see Threads, IPC 


MyGloballd 

Global ID of the thread. 

MyLocalld 

Local ID of the thread. 

ProcessorNo 

The processor number on which the thread currently executes. 

UserDefinedHandle 


This field can be freely set and read by user threads. It can. e.g., be used for storing a thread 
number, a pointer to an additional user thread control block, etc. 
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Generic Programming Interface 

The listed generic functions permit user code to access TCRs independently of the processor-specific TCR model. All 
functions are user-level functions; the microkernel is not involved. 

#include <l4/thread.h> 

Threadld MyLocalld () 

Threadld MyGloballd () 

Delivers the local/global ID of the currently running thread (see TCRs, page 16). 

Threadld Myself () 

{ MyGloballd () } 

int ProcessorNo () 

Delivers the processor number the current thread is running on. Delivered value is a valid index 
into the processor description array (see Kernel Interface Page, page 4). 

Word UserDefinedHandle () 

void Set UserDefinedHandle (Word NewValue ) 

Delivers/sets the user defined handle of the currently running thread. 

Threadld Pager () 

void Set-Pager (Threadld NewPager ) 

Delivers/sets the pager for the currently running thread. 

Threadld ExceptionHandler () 

void Set -ExceptionHandler (Threadld NewHandler ) 

Delivers/sets the exception handler for the currently running thread. 

void SetjCopFlag (Word n) 

void Clr _CopFIag (Word n) 

Sets/clears coprocessor flag c n . 

Word ErrorCode () 

Delivers the error code of the last system-call. 

Word XferTimeouts () 

void Set -XferTimeouts (Word NewValue ) 

Delivers/sets the transfer timeouts for the currently running thread (see IPQ page 61). 

Threadld IntendedReceiver () 

Delivers the intended receiver of last received IPC (see IPQ page 62). 

Threadld ActualSender () 

Delivers the actual sender of the last propagated IPC (see IPQ page 61). 

void Set_VirtuaISender (Threadld t) 

Sets the virtual sender for the next deceiving IPC (see IPC, page 61). 


Code generators of IDL and other compilers are not restricted to the generic interface. They can use any processor-specific 
methods and optimizations to access TCRs. 
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2.3 ExchangeRegisters [Systemcall] 


Threadld 

dest 

Word 

control 

Word 

SP 

Word 

IP 

Word 

FLAGS 

Threadld 

pager 

Word 

UserDefinedHandle 


Threadld 

result 

Word 

control 

Word 

SP 

Word 

IP 

Word 

FLAGS 

Threadld 

pager 

Word 

UserDefinedHandle 


Exchanges or reads a thread's FLAGS, SP, and IP hardware registers as well as pager and UserDefinedHandle TCRs. 
Furthermore, thread execution can be suspended or resumed. The destination thread must be an active thread (see page 22) 
residing in the invoker’s address space. 

Any IP, SP, or FLAGS modification changes the corresponding user-level registers of the addressed thread. In general, 
ongoing kernel activities are not influenced. However, a currently active IPC operation can be canceled or aborted. For 
details see the SR- bit specification below. 

Modifications of the pager TCR and the UserDefinedHandle TCR become immediately effective, whether the desti- 
nation thread executes in user mode or in kernel mode. 


Input Parameters 


rfggf Thread ID of the addressed thread. This may be a local or a global ID. However, the addressed 

thread must reside in the current address space. Using a local thread ID might be substantially 
faster in some implementations. 


control 


0 ( 23 / 55 ) 


hpu f i s S R H 


hpu f is The s-flag refers to the SP register, i to IP, f to FLAGS, u to the UserDefinedHandle TCR, p to 

the pager TCR, and h to the Tf-flag. If a flag is set to 1, the register/state is overwritten by the 
corresponding input parameter. Otherwise, the corresponding input parameter is ignored and the 
register/state is not modified. 

§ f> Controls whether the addressed thread’s ongoing IPC opereration should be canceled/aborted 

through the system call or not. 

g _ q An IPC operation of the addressed thread that is currently waiting to send a message or is sending 
a message will continue as usual. SP, IP or FLAGS modifications are delayed until the IPC 
operation terminates. 


An IPC operation of the addressed thread that is currently waiting to send a message will be 
canceled. An IPC operation that is currently sending a message will be aborted. 


An IPC operation of the addressed thread that is currently waiting to receive a message or is 
receiving a message will continue as usual. SP, IP or FLAGS modifications are delayed until the 
IPC operation terminates. 

An IPC operation of the addressed thread that is currently waiting to receive a message will be 
canceled. An IPC operation that is currently receiving a message will be aborted. 


H 


Halts/resumes the thread if h = 1. Ignored for h = 0. 


H = 0 


No effect if the thread was not halted. Otherwise, thread execution is resumed. 
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H = 1 

User-level thread execution is halted. Note that ongoing IPCs and other kernel operations are 
not affected by H. (See SR for also aborting active IPC.) 

SP 

The current user- level stack pointer is set to SP if s = 1. Ignored for s = 0. 

IP 

The current user- level instruction pointer is set to IP if i = 1. Ignored for i = 0. 

FLAGS 

Sets the user-level processor flags of the thread if / = 1. Ignored for / = 0. The semantics of 
the FLAGS word depends on the processor type. 

UserDefinedHandle 

Sets the thread’s UserDefinedHandle TCR if u = 1 . Ignored for u — 0. 

pager 

Sets the thread’s pager TCR if p = 1 . Ignored for p = 0. 


Output Parameters 


result A nilthread, input parameter dest was a local thread ID 

global thread ID of the addressed thread. EXCHANGEREGISTERS succeeded. 

result A nilthread, input parameter dest was a global thread ID 

local thread ID of the addressed thread. EXCHANGEREGISTERS succeeded. 

result = nilthread Operation failed. The ErrorCode TCR indicates the reason for the failure. 


ErrorCode [TCR] Set if result = nilthread. Undefined if result A nilthread. 

_ 2 Invalid thread. The dest parameter specified an invalid thread ID, an inactive thread, or a thread 

within a different address space. 


control 


Reports whether the addressed thread was halted (H = 1) or not (H = 0) when EXCHANGE- 
REGISTERS was invoked. Note that this output control bit is independent of the input parameter 
control. 

Reports whether the addressed thread was within an IPC operation when EXCHANGEREGIS- 
TERS was invoked. A value of 0 reports that the addressed thread was not within a send phase 
(5 = 0) or not within a receive phase (R = 0), respectively. Note that these output control bits 
are independent of the input parameter control. 

Operation was executed while the addressed thread was within the receive phase of an IPC 
operation. Iff the input control word had R = 1 the IPC operation was canceled or aborted. 



S = 1 


Operation was executed while the addressed thread was within the send phase of an IPC opera- 
tion. Iff the input control word had 5 = 1 the IPC operation was canceled or aborted. 
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SP 


Old user-level stack pointer of the thread. 


IP 


Old user-level instruction pointer of the thread. 


FLAGS Old user-level flags of the thread. The semantics of this word is processor specific. 


UserDefinedHandle 

Old content of thread’s UserDefinedHandle TCR. 


pager Old content of thread's pager TCR. 


No pagefaults will happen. 


Pagefaults 


Generic Programming Interface 

System-Call Function: 

#include <l4/thread.h> 

Threadld ExchangeRegisters ( Threadld dest, Word control , sp, ip, flags, UserDefinedHandle, Threadld pager, 
Word& old-control, old_sp, oldJp, old-flags, old_UserDefinedHand!e, Threadld& old-pager ) 


Convenience Programming Interface 

Derived Functions: 

#include <l4/thread.h> 

Threadld Globalld ( Threadld t) [GloballdOj] 

{ if (IsLocalld (t)j ExchangeRegisters (t,0,-. . . ) else t } 

Delivers global ID of specified local thread. Specifying a non-local thread delivers nilthread. 

Threadld Localld ( Threadld t) [LocalldOf\ 

{ if (IsGloballd (t)) ExchangeRegisters (t,0,-. . . ) else t } 

Delivers local ID of specified local thread. Specifying a non-local thread delivers nilthread. 

Word UserDefinedHandle ( Threadld t ) [ UserDefinedHandleOf ] 

void Set -UserDefinedHandle ( Threadld t, Word handle ) [Set_UserDefinedHandleOf] 

Delivers/sets the user defined handle of specified local thread. Result of specifying a non-local 
thread is undefined. 

Threadld Pager (Threadld t) [PagerOf] 

void Set_Pager (Threadld t, p) [Set_PagerOf\ 

Delivers/sets the pager for specified local thread. Result of specifying a non-local thread is 
undefined. 
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void Start (Threadld t) 

void Start (Threadld t, Word sp, ip) [Start_SpIp\ 

void Start ( Threadld t, Word sp, ip, flags ) [ Start .SpIpFlags ] 

Resume execution of specified local thread (if halted). Abort any ongoing IPC operations. Op- 
tionally modify stack pointer, instruction pointer, and processor flags according to function pa- 
rameters. Result of specifying a non-local thread is undefined. 

ThreadState Stop ( Threadld t) 

ThreadState Stop ( Threadld t, Word& sp, ip, flags) [ Stop_SpIpFlags ] 

Halt execution of specified local thread and return its current thread state. Do not abort any on- 
going IPC operation. Optionally return thread's stack pointer, instruction pointer, and processor 
flags in output parameters. Result of specifying a non-local thread is undefined. 

ThreadState Abort Receive and stop ( Threadld t) 

ThreadState AbortReceivejand^top (Threadld t, Word& sp, ip, flags) [AbortReceive_andMop_SpIpFlags\ 

As stop ( ), except any ongoing IPC receive operation is immediately aborted. 


ThreadState AhortSend and stop ( Threadld t) 

ThreadState AbortSendjandjtop (Threadld t, Word& sp, ip, flags) [AbortSend_andjtop_SpIpFlags] 

As stop (), except any ongoing IPC send operation is immediately aborted. 


ThreadState Ahortlpc and stop ( Threadld t) 

ThreadState Abortlpc jand stop (Threadld t, Word& sp, ip, flags) [Abortlpc-and^stopSpIpFlags] 

As stop (), except any ongoing IPC send or receive operations are immediately aborted. 


Support Functions: 

#include <l4/thread.h> 

struct ThreadState { Word raw } 


Bool ThreadWasHalted ( ThreadState s) 

Bool ThreadWasSending (ThreadState s) 

Bool ThreadWasReceiving ( ThreadState s) 

Bool ThreadWasIpcing (ThreadState s) 

Query the thread state returned from one of the stop ( ) functions. 

Word ErrorCode () 

Word ErrlnvalidThread 
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2.4 ThreadControl [Privileged Systemcall] 


Threadld dest 
Threadld SpaceSpecifier 
Threadld scheduler 
Threadld pager 
void* UtcbLocation 


Word result 


A privileged thread, e.g., the root server, can delete and create threads through this function. It can also modify the global 
thread ID (version field only) of an existing thread. 

Threads can be created as active or inactive threads. Inactive threads do not execute but can be activated by active 
threads that execute in the same address space. 

An actively created thread starts immediately by executing a short receive operation from its pager. (An active thread 
must have a pager.) The actively started thread expects a start message (MsgTag and two untyped words) front its pager. 
Once it receives the start message, it takes the value of MR i as its new IP, the value of MR 2 as its new SP, and then 
starts execution at user level with the received IP and SP. 

Interrupt threads are treated as normal threads. They are active at system startup and can not be deleted or migrated 
into a different address space (i.e., SpaceSpecifier must be equal to the interrupt thread ID). When an interrupt occurs the 
interrupt thread sends an IPC to its pager and waits for an empty end-of-interrupt acknowledgment message (MRo=0). 
Interrupt threads never raise pagefaults. To deactivate interrupt message delivery the pager is set to the interrupt thread's 
own ID. 


Input Parameters 


tf es f Addressed thread. Must be a global thread ID. Only the thread number is effectively used 

to address the thread. If a thread with the specified thread number exists, its version bits are 
overwritten by the version bits of dest id and any ongoing IPC operations are aborted. Otherwise, 
the specified version bits are used for thread creations, i.e., a thread creation generates a thread 
with ID dest. 


SpaceSpecifier A nilthread, dest not existing 

Creation. The space specifier specifies in which address space the thread will reside. Since 
address space do not have own IDs, a thread ID is used as SpaceSpecifier. Its meaning is: the 
new thread should execute in the same address space as the thread SpaceSpecifier. 

The first thread in a new address space is created with SpaceSpecifier = dest. This operation 
implicitly creates a new empty address space. Note that the new address space is created with an 
empty UTCB and KIP area. The space creation must therefore be completed by a SpaceCon- 
TROL operation before the thread(s) can execute. 

SpaceSpecifier A nilthread, dest exists 

Modification Only. The addressed thread dest is neither deleted nor created. Modifications can 
change the version bits of the thread ID, the associated scheduler, the pager, or the associated 
address space, i.e., migrate the thread to a new address space. 

SpaceSpecifier = nilthread, dest exists 

Deletion. The addressed thread dest is deleted. Deleting the last thread of an address space 
implicitly also deletes the address space. 


scheduler T nilthread 

Defines the scheduler thread that is permitted to schedule the addressed thread. Note that the 
scheduler thread must exist when the addressed thread starts executing. 
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scheduler = nilthread 

The current scheduler association is not modified . This variant is illegal for a creating THREAD- 
CONTROL operation. 


pager ^ nilthread The pager of dest is set to the specified thread. If dest was inactive before, it is activated. 

pager = nilthread The current pager association is not modified. 

If used with a creating THREADCONTROL operation, dest is created as an inactive thread. 


UtcbLocation ^ -1 The start address of the UTCB of the thread is set to UtcbLocation. Upon thread activation the 
UTCB must fit entirely into the UTCB area of the configured address space, and must be prop- 
erly aligned according to the Utcblnfo field of the kernel interface page. It is the application’s 
responsibility to ensure that UTCBs of multiple threads do not overlap. Changing the UtcbLo- 
cation of an already active thread is an illegal operation. Note that since a newly created space 
has an empty UTCB area, it is not possible to activate a thread in an address space which has 
not been properly configured with SPACECONTROL. 

UtcbLocation = -1 The UTCB location is not modified. 


Utcblnfo [KernellnterfacePage Field] 

Permits to calculate the appropriate page size of the UTCB area fpage and specifies the size and 
alignement of UTCBs. Note that the size restricts the total number of threads that can reside in 
an address space. 


~ (10/42) 

s (6) 

a (6) 

m (10) 


s The minimal area size for an address space’s UTCB area is 2 s . The size of the UTCB area limits 

the total number of threads k to 2 a mk < 2 s . 

m UTCB size multiplier. 

a The UTCB location must be aligned to 2°. The total size required for one UTCB is 2 a m. 


Output Parameters 


result The result is 1 if the operation succeeded, otherwise the result is 0 and the ErrorCode TCR 

indicates the failure reason. 


ErrorCode [TCR] Set if result = 0. Undefined if result t^O. 

= 1 No privilege. Current thread does not have have privilege to perform the operation. 

_ 2 Unavailable thread. The dest parameter specified a kernel thread or an unavailable interrupt 

thread. 

_ 3 Invalid space. The SpaceSpecifier parameter specified an invalid thread ID, or activation of a 

thread in a not yet initialized space. 

_ q Invalid scheduler. The scheduler paramter specified an invalid thread ID, or was set to nilthrad 

for a creating THREADCONTROL operation. 

_ g Invalid UTCB location. UtcbLocation lies outside of UTCB area, or attempt to change the 

UtcbLocation for an already active thread. 
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= 8 Out of memory. Kernel was not able to allocate the resources required to perform the operation. 


No pagefaults will happen. 


Pagefaults 


Generic Programming Interface 

System-Call Function: 

#include <l4/thread.h> 

Word ThreadControI ( Threadld dest, SpaceSpecifier, Scheduler, Pager, void* UtcbLocation) 


Convenience Programming Interface 

Derived Functions: 

#include <l4/thread.h> 

Word Associatelnterrupt ( Threadld InterruptThread, InterruptHandler ) 

{ ThreadControI (InterruptThread, InterruptThread, nilthread, InterruptHandler, - 1 ) } 

Associate a handler thread with the specified interrupt source. 

Word Deassociatelnterrupt ( Threadld InterruptThread) 

{ ThreadControI (InterruptThread, InterruptThread, nilthread, InterruptThread, -1) } 

Remove association between the specified interrupt source and any potential handler thread. 


Support Functions: 

Word ErrorCode () 

Word ErrNoPrivilege 
Word ErrlnvalidThread 
Word ErrlnvalidSpace 
Word ErrlnvaUdScheduler 
Word ErrUtcbArea 
Word ErrNoMem 



Chapter 3 


Scheduling 
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3.1 Clock [Data Type] 


On both 32-bit and 64-bit processors, the system clock is represented as a 64-bit unsigned counter. The clock measures 
time in 1 /is units, independent of the processor frequency. Although the clock base is undefined, it is guaranteed that the 
counter will not overflow for at least 1,000 years. 


Generic Programming Interface 

#include <l4/schedule.h> 

struct Clock { Word64 raw } 

Convenience Programming Interface 


#include <l4/schedule.h> 


Clock + (Clock l, int r ) 


Clock + (Clock 1, Word64 r) 

[ClockAddU sec] 

Clock — (Clock l, int r) 


Clock — (Clock l, Worcl64 r) 

[ClockSubU sec] 

Adds/subtracts a number of /is to/from a clock value. Delivers 

new clock value. Does not 

modify the old clock value. 


Bool < ( Clock l, r) 

[IsClockEarlier] 

Bool > (Clock l, r ) 

[IsClockLater] 

Boo! <= ( Clock l, r ) 


Bool >= (Clock l, r) 


Bool == (Clock l, r) 

[IsClockEqual] 

Bool ! = ( Clock l, r) 

[IsClockNotEqual] 

Compares two clock values. 




SYSTEMCLOCK 


27 


3.2 SystemClock [Systemcall] 

> Clock clock 


Delivers the current system clock. Typically, the operation does not enter kernel mode. 


No pagefaults will happen. 

Pagefaults 

System-Call Function: 

Generic Programming Interface 

#include <l4/schedule.h> 


Clock SystemClock () 
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3.3 Time [Data Type] 


Time values are used to specify send/receive timeouts for IPC operations (see page 60) and time quanta for scheduling 
(see page 31). The unit for time periods as well as for time points is 1 ps. Clock ticks thus happen every ps. 

Relative time values specify a time period. Time periods are encoded as un-normalized 16-bit floating-point numbers. 
(Note that for easier handling the mantissa can have leading 0-bits.) The shortest non-zero time period that can be 
specified is 1 ps, the longest finite period slightly exceeds 610 hours. Two special periods frequently used for timeouts 
are 0 and oo, a never ending period. The values 0 and oo have special encodings. 


time period: 


’ ( 5 ) 


■( 10 ) 


= 2 e m ps 


’( 16 ) 


0 1 


( 5 ) 


'( 10 ) 


= 0 


Absolute time values specify a point in time. They are only valid for a limited period, at maximum 67 seconds. 


time point: 


' ( 4 ) 


■ ( 10 ) 


For a semantical description of time-point values, we use Clock to denote the current clock value in ps, xm to denote 
bit i of x, and xuj] to denote the number consisting of bits i to j of x. Then, the time-point value (c, m, e) specifies the 
point: 



2 e • 

(m + Clock [e3e+9] 

• 2 10 ) 

if 

C(ocfcj e+10 j = c 

T ■ 

(m + Clock [63e+9] 

• 2 10 + 2 10 ) 

if 

Clock [e+10] c 


Absolute time values are thus the more precise the nearer in the future they are. 

Absolute time values with maximal precision become invalid just after the clock has reached the specified point in 
time. The validity interval can be expanded, but only by reducing the precision. In general, a time-point value (c, m, e) 
that is constructed when the current clock value is Co is valid from Co up to 

C 0 + (2 10 - 1) • 2 e 

Therefore, a time-point value that should remain valid for 10 ms can have a precision of 10 ps whereas a value that 
should remain valid for an entire second can only have a precision of 1 ms. In general, a precision of 0.1% of the required 
validity interval can be achieved. 


Generic Programming Interface 

#include <l4/schedule.h> 
struct Time {Word16raw} 


Time Never 
Time ZeroTime 

Time TimePeriod (Word64 microseconds) 
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Time TimePoint ( Clock at) 


Convenience Programming Interface 

#include <!4/schedule.h> 


Time + ( Time l, Word r) 

[TimeAddU sec] 

Time + = (Time l, Word r) 

[TimeAddUsecTo] 

Time — ( Time l. Word r) 

[TimeSubU sec] 

Time — = (Time l, Word r) 

[TimeSubU secFrom] 

Adds/subtracts a number of microseconds to/from a time value. 


Time + (Time l, r) 

[TimeAdd] 

Time + = (Time l, r) 

[TimeAddTo] 

Time — (Time 1, r) 

[TimeSub] 

Time — = (Time l, r) 

[TimeSubFrom] 

Adds/subtracts a time period to/from a time value. The result of adding/subtracting a time point 

is undefined. 


Bool > (Time l, r) 

[IsTimeLonger] 

Bool >= (Time 1, r) 


Bool < ( Time l, r) 

[IsTimeShorter] 

Bool <= ( Time 1, r) 


Bool == ( Time I, r) 

[IsTimeEqual] 

Bool ! = (Time I, r) 

[IsTimeNotEqual] 


Compares two time values. The result of comparing a time period with a time point, or vice 
versa, is undefined. 
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3.4 ThreadSwitch [Systemcall] 

Threadld dest > void 


The invoking thread releases the processor (non-preemptively) so that another ready thread can be processed. 


Input Parameter 


dest = nilthread Processing switches to an undefined ready thread which is selected by the scheduler. (It might 
be the invoking thread.) Since this is “ordinary” scheduling, the thread gets a new timeslice. 

dest ¥= nilthread If dest is ready, processing switches to this thread. In this “extraordinary” scheduling, the invok- 
ing thread donates its remaining timeslice to the destination thread. (This one gets the donation 
in addition to its ordinarily scheduled timeslices, if any.) 

If the destination thread is not ready or resides on a different processor, the system call operates 
as described for dest = nilthread. 


No pagefaults will happen. 


Pagefaults 


Generic Programming Interface 

System-Call Function: 

#include <l4/schedule.h> 

void ThreadSwitch ( Threadld dest) 


Convenience Programming Interface 

Derived Functions: 

#include <l4/schedule.h> 

void Yield () 

{ ThreadSwitch (nilthread) } 

Switch processing to a thread selected by the scheduler. 
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3.5 Schedule [Systemcall] 

Threadld dest 

Word time control 

Word processor control 

Word prio 

Word preemption control 


Word result 
Word time control 


The system call can be used by schedulers to define the priority, timeslice length, and other scheduling parameters of 
threads. Furthermore, it delivers thread states. 

The system call is only effective if the calling thread is defined as the destination thread’s scheduler (see thread control 
page 22). 


Input Parameters 

dest 

Destination thread ID. The destination thread must be existent (but can be inactive) and the cur- 
rent thread must be defined as the destination thread's scheduler (see thread control). Otherwise, 
the destination thread is not affected. 

All further input parameters have no effect if the supplied value is —1, ensuring that the corresponding internal thread 
variable is not modified. The following description always refers to values ¥= — 1. 






time control 

ts len (16) 

total quantum 


ts ten 

New timeslice length for the destination thread. The timeslice length is specified as a time 
period (see page 28). Absolute time values and the value 0 are illegal. A timeslice length of 
oo, however, can be specified. In that case, the thread never experiences a preemption due to 
exhausted time slice. The specified value is always rounded up to the nearest possible timeslice 
length. In particular, a time period of 1 p, s results in the shortest possible timeslice. 

Writing the timeslice length initializes the current quantum with the new length. After the quan- 
tum is exhausted, the thread is preempted while the quantum is reloaded with ts len for the next 
timeslice. 

total quantum 

Defines the total quantum for the thread. Exhaustion of the total quantum results in an RPC to 
the thread's scheduler (i.e., the current thread). (Re)writing the total quantum re-initializes the 
quantum, independent of the already consumed total quantum. The total quantum is specified 
as a time period (see page 28). Absolute time values are illegal. A total quantum of oo can be 
specified. 






prio 

0 (24/56) 

prio (8) 



New priority for destination thread. Must be less than or equal to current thread’s priority. 


preemption control 


0 ( 8 / 40 ) 


sensitive prio (gj 


maximum delay 


sensitive prio Preemptions by threads that run on a priority lower or equal to this sensitive prio will, (a) if 
the delay-preemption flag is set, be delayed until the thread executes a thread switch (nilthread) 
system call; and (b) if the signal-preemption flag is set, raise a preemption fault to the exception 
handler. 

No preemption delays or signaling will occur if preempted by a thread having a higher priority 
than sensitive prio , regardless of the state of the delay-preemption and signal-preemption flags. 
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maximum delay The maximum time in /its a pending preemption can be delayed in the destination thread. The 
value 0 effectively disables preemption delay. 


processor control 


processor number Specifies the processor number to which the thread should be migrated. The processor number 
must be valid, i.e., smaller than the total number of processors (see kernel interface page at 
page 3). Otherwise, the parameter is ignored. The first processor number is denoted as 0. 


0 ( 16 / 48 ) 


processor number 


Output Parameters 


result 

tstate = 

0 

1 

2 

3 

4 

5 

6 

7 


( 24 / 56 ) 


tstate (s) 


Thread state: 

Error. The operation failed completely. The ErrorCode TCR indicates the reason for the failure. 


Dead. The thread is unable to execute or does not exist. 

Inactive. The thread is inactive/stopped. 

Running. The thread is ready to execute at user-level. 

Pending send. A user-invoked IPC send operation currently waits for the destination (recipient) 
to become ready to receive. 

Sending. A user-invoked IPC send operation currently transfers an outgoing message. 

Waiting to receive. A user-invoked IPC receive operation currently waits for an incoming mes- 
sage. 

Receiving. A user-invoked IPC receive operation currently receives an incoming message. 


ErrorCode [TCR] Set if lower 8 bits of result = 0. Undefined if lower 8 bits of result 5^0. 

= 1 No privilege. Current thread is not the scheduler of the destination thread. 

= 2 The dest parameter specified an invalid thread ID. 

_ g Invalid parameter. The specified time-slice length, total quantum, priority, or processor number 

was invalid. 


time control 

rent ts 

rem total Remaining total quantum of the thread. 


1 ( 16 ) 


rem total 


( 16 ) 


Remainder of the current timeslice. 
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No pagefaults will happen. 


Pagefaults 


System-Call Function: 

#include <l4/schedule.h> 


Generic Programming Interface 


Word Schedule ( Threcidld dest, Word TimeControl, ProcessorControl, prio, PreemptionControl, Word& 

old _Time Control) 


Convenience Programming Interface 

Derived Functions: 

#include <l4/schedule.h> 

Word SetJPriority ( Threadld dest, Word prio) 

{ Schedule (dest, -1, -1, prio, -1) } 

Word SetJProcessorNo ( Threadld dest, Word ProcessorNo) 

{ Schedule (dest, -1, ProcessorNo, -1,-1) } 

Word Timeslice ( Threadld dest, Time & ts, Time & tq) 

Delivers the remaining timeslice and total quantum of the given thread. 

Word Set Timeslice ( Threadld dest, Time ts, Time tq) 

{ Schedule (dest, ts * 2 16 + tq, -1, -1, -1) } 

Word SetJ’reemptionDelay (Threadld dest, Word sensitive Prio, Word maxDelay) 

{ Schedule (dest, -1, -1, -1, SensitivePrio * 2 16 + MaxDelay) } 


Support Functions: 

Word ErrorCode () 
Word ErrNoPrivilege 
Word ErrlnvalidThread 
Word ErrlnvalidParam 



34 


PREEMPT FLAGS 


3.6 Preempt Flags [tcrj 


The preemption flags TCR controls asynchronous preemptions (timeslice exhausted or activation of a higher-priority 
thread including device interrupts). 


Preempt Flags 


Ids 


The ds-flags are used to control the microkernel. User threads can set/reset them. The /-flag 
signals an event to the user. It is set by the microkernel and typically read/reset by the user. 

s — 0 Asynchronous preemptions are not signaled to the exception handler. 

„ = | Asynchronous preemptions are signaled as preemption faults to the exception handler. If d = 0 

this happens immediately. Otherwise, it is delayed until the thread continues execution after the 
preemption. 

^ _ q All asynchronous preemptions happen immediately. If they are signaled as preemption faults 

(s = 1), this happens after the preemption took place, i.e., when the thread gets reactivated. 

^ _ i Asynchronous preemptions are delayed if the priority of the preemptor is lower or equal than 

the sensitive priority for the current thread. (The sensitive priority is set by the scheduler, see 
page 31.) A delayed preemption does not interrupt the current thread immediately but is post- 
poned until the current thread invokes a systemcall thread switch (nilthread). However, a pend- 
ing preemption must not be delayed for longer than the maximum delay that was set by the 
thread’s scheduler. Such a preemption-delay overflow resets the d bit and is signaled to the 
exception handler. 

7 = 0 No asynchronous preemption is pending. 

j _ ^ An asynchronous preemption is currently pending, i.e.. the thread should as soon as possible 

reset the d-flag and invoke thread switch. Invoking thread switch re-enables the maximum delay 
for the next delayed asynchronous preemption. 

Invoking thread switch is not required if no asynchronous preemption is pending (7 = 0) after 
the user thread has reset the d-flag. 


Generic Programming Interface 

#include <l4/schedule.h> 

Bool EnablePreemptionFaultException () 

Bool DisablePreemptionFaultException () 

Sets/resets the s-flag and delivers the old s-flag value (true = set). 

Bool DisablePreemption () 

Bool EnablePreemption () 

Sets/resets the d-flag and delivers the old d-flag value (true = set). 
Bool PreemptionPending () 

Resets the 7-flag and delivers the old 7-flag value (true = set). 




Chapter 4 


Address Spaces and 

Mapping 
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4.1 Fpage [Data Type] 


Fpages (Flexpages) are regions of the virtual address space. An fpage consists of all pages mapped actually in this region 
sans kernel mapped objects, i.e., kernel interface page and UTCBs. Fpages have a size of at least 1 K. For specific 
processors, the minimal fpage size may be larger; e.g., a Pentium processor offers a minimal page size of 4 K while the 
Alpha processor offers smallest pages of 8 K. Fpages smaller than the minimal page size are treated as nilpages. The 
kernel interface page (see page 3) specifies which page sizes are supported by the hardware/kemel. An fpage of size 2 s 
has a 2 s -aligned base address 6, i.e., 6 = 0 (mod 2 s ), where s>10 for all architectures. 

Mapped fpages are considered inseparable objects. That is, if an fpage is mapped, the mapper can not later partially 
unmap the mapped page; the whole fpage must be unmapped in a single operation. The mappee can. however, separate 
the fpage and map fpages (objects) of smaller size. Partially unmapping an fpage might or might not work on some 
systems. The kernel will give no indication as to whether such an operation succeeded or not. 


fpage (6,2 s ) 


b/2 10 ( 22 / 54 ) 


S (6) 


Orwx 


Special fpage denoters describe the complete user address space and the nilpage , an fpage which has no base address and 
a size of 0: 


complete 


0 ( 22 / 54 ) 


S - 1 (6) 


Orwx 


nilpage 


0 ( 32 / 64 ) 


Access Rights 


The rwx bits define the accessibility of the fpage: 

r readable 
w writable 
x executable 

A bit set to one permits the corresponding access to the newly-mapped/granted page provided 
that the mapper itself possesses that access right. If the mapper does not have the access right 
itself or if the bit is set to zero the mapped/granted page will not get the corresponding access 
right. 

Note that processor architectures may impose restrictions on the access-right combinations. 
However, read-only (including execute), rwx = 101, and read/write/execute, rwx = 111, 
should be valid for any processor architecture. The kernel interface page (see page 3) specifies 
which access rights are supported in the processor architecture. 


Generic Programming Interface 


#include <l4/space.h> 
struct Fpage { Word raw } 


Word Readable 
Word Writable 
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Word executable 
Word Fully Accessible 
Word ReadeXecOnly 
Word NoAccess 


Fpage Nilpage 

Fpage CompleteAddressSpace 


Bool IsNilFpage (Fpage f) 

{ f == Nilpage } 

Fpage Fpage (Word BaseAddress, int FpageSize > IK) 

Fpage FpageLog2 ( Word BaseAddress, int Log2FpageSize < 64) 

Delivers an fpage with the specified location and size. 

Word Address (Fpage f) 

Word Size (Fpage f) 

Word SizeLog2 (Fpage f) 

Delivers address/size of specified fpage. 

Word Rights (Fpage f) 

void SetJRights (Fpage&f Word AccessRights) 

Delivers/sets the access rights for the specified fpage. 


Fpage + (Fpage f, Word AccessRights) 
Fpage += (Fpage f, Word AccessRights) 
Fpage — (Fpage f, Word AccessRights) 
Fpage —= (Fpage f, Word AccessRights) 


[Fpage AddRights] 
[ FpageAddRightsTo ] 
[. FpageRemoveRights ] 
[ FpageRemoveRightsFrom ] 


Adds/removes specified access rights from fpage. Delivers new fpage value. 
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4.2 Unmap [Systemcall] 


Word control 


void 


The specified fpages (located in MRo...) are unmapped. Fpages are mapped as part of the IPC operation (see page 59). 


Input Parameters 


control 


0 (25/57) 


/ 


k (6) 


Specifies the highest MR k that holds an fpage to be unmapped. The number of fpages is thus 
k + 1. 

f = 0 The fpages are unmapped recursively in all address spaces in which threads of the current ad- 
dress space have mapped them before. However, the fpages remain unchanged in the current 
address space. 

f — 1 The fpages are unmapped like in the / = 0 case and, in addition, also in the current address 
space. 


FpageList MR o ...k Fpages to be processed. 


Fpage MR , 


fpage ( 28 / 58 ) 


0 rwx 


Fpage to be unmapped. (The term unmapped is used even if effectively no access right is re- 
moved.) A nilpage specifies a no-op. 


Q rwx Any access bit set to 1 revokes the corresponding access right. A 0-bit specifies that the corre- 

sponding access right should not be affected. Typical examples: 


=0111 Complete unmap of the fpage. 


=0010 Partial unmap, revoke writability only. As a result, the fpage is set to read-only. 

_qqqq No unmap. This case is particularly useful if only dirty and accessed bits should be read and 

reset without changing the mapping. 


Output Parameters 


FpageList MR o ...k The accessed status bits in the fpages are updated. 
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Fpage MR , 


fpage (28/58) 


0 RWX 


R - 0 


R- 1 




VF = 1 


X = 0 


The status bits Referenced , Written, and eXecuted of all pages processed by the unmap operation 
are reset and the bitwise OR-ed old values of all the processed pages are delivered in MR 0 ...fc. 
For processors that do not differentiate between read access and execute access, the R. and A' 
bits are unified: either both are set or both are reset. Resetting status bits is not a recursive 
operation. However, the status bit values for pages within the current space will also reflect 
accesses performed on recursive mappings. 

No part of the fpage has been Referenced after the last unmap operation (or after the initial map 
operation). This includes all recursively mapped pages. 

Remark: The meaning of referenced slightly differs from read. Not being referenced means that 
not only no read access but that also no write and execute access occurred. 

At least one page of the specified fpage (including all recursive mappings) has been referenced 
after the last unmap operation (or after the initial map operation). All in-kernel R bits are reset 
Remark: The meaning of referenced slightly differs from read. Write accesses and execute 
accesses also set the R bit. 

No part of the fpage has been written after the last unmap operation (or after the initial map 
operation), i.e., the fpage is clean. This includes all recursively mapped pages. 

At least one page of the specified fpage (including all recursive mappings) has been written after 
the last unmap operation (or after the initial map operation), i.e., the fpage is dirty. 

All in-kernel dirty bits are reset. 

No part of the fpage has been eXecuted after the last unmap operation (or after the initial map 
operation). This includes all recursively mapped pages. 


X - I At least one page of the specified fpage (including all recursive mappings) has been executed 

after the last unmap operation (or after the initial map operation). All in-kernel A bits are reset. 
Remark: For processors that do not differentiate between read and execute accesses, the A' bit 
is set to 1 iff R = 1. 


No pagefaults will happen. 

Pagefaults 

System-Call Function: 

Generic Programming Interface 

#include <l4/space.h> 


void Unmap (Word control) 



Derived Functions: 


Convenience Programming Interface 


#include <!4/space.h> 


Fpage Unmap (Fpage f) [UnmapFpage] 

{ LoadMR (0, f); Unrnap (0); StoreMR (0, f); f } 

void Unmap (Word n, Fpage& [n] fpages) [ UnmapFpages \ 

{ LoadMRs (0, n, fpages); Unmap (n — 1); StoreMRs (0, n, fpages); } 


Recursively unmaps the specified fpage(s) from all address spaces except the current one. 
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Fpage Flush ( Fpagef) 

{ LoadMR (0, f); Unmap (64); StoreMR (0, f); f } 

void Flush (Word n, Fpage& [n] fpages) [FlushFpages] 

{ LoadMRs (0, n, fpages); Unmap (64 + n — 1); StoreMRs (0, n, fpages); } 

Recursively unmaps the specified fpage(s) from all address spaces, including the current one. 

Fpage GetStatus (Fpagef) 

{ LoadMR (0, f — Fully A ccessihle) ; Unmap (0); StoreMR (0, f); f } 

Resets and delivers the status bits of the specified fpage. 

Bool WasReferenced (Fpagef) 

Bool WasWritten ( Fpagef) 

Bool WaseXecuted (Fpagef) 

Checks the status bits of specified fpage. The specified fpage must be the output of an Unmap (), 
Flush (), or GetStatus () function. 
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4.3 SpaceControl [Privileged Systemcall] 


Threadld 

Word 

Fpage 

Fpage 

Threadld 


SpaceSpecifier > 

control 

KernellnterfacePageArea 

UtcbArea 

Redirector 


Word result 
Word control 


A privileged thread, e.g., the root server, can configure address spaces through this function. 


Input Parameters 


SpaceSpecifier Since address spaces do not have ids, a thread ID is used as SpaceSpecifier. It specifies the 
address space in which the thread resides. The SpaceSpecifier thread must exist although it may 
be inactive or not yet started. In particular, the thread may reside in an empty address space that 
is not yet completely created. 


KernellnterfacePageArea 

Specifies the fpage where the kernel should map the kernel interface page. The supplied fpage 
must have a size specified in the KipArealnfo field of the kernel interface page, must fit entirely 
into the user-accessible part of the address space and must not overlap with the UTCB area (see 
below). Address 0 of the kernel interface page is mapped to the fpage’s base address. 

The value is ignored if there is at least one active thread in the address space. 


KipArealnfo [KernellnterfacePage Field] 

Permits calculation of the appropriate page size of the Kernellnterface area fpage. 


( 26 / 58 ) 


S (6) 


s The size of the kernel interface page area is 2 s . 


UtcbArea Specifies the fpage where the kernel should map the UTCBs of all threads executing in the 

address space. The fpage must fit entirely into the user-accessible part of an address space and 
must not overlap with the KIP area. The fpage size has to be at least the smallest supported 
hardware-page size. In fact, the size of the UTCB area restricts the maximum number of threads 
that can be created in the address space. See the kernel interface page for the space and alignment 
that is required for UTCBs. 

The value is ignored if there is at least one active thread in the address space. 


Utcblllfo [KernellnterfacePage Field] 

Permits to calculate the appropriate page size of the UTCB area fpage and specifies the size and 
alignment of UTCBs. Note that the size restricts the total number of threads that can reside in 
an address space. 


~ ( 10 / 42 ) 

S ( 6 ) 

a ( 6 ) 

m ( 10 ) 


The minimal area size for an address space’s UTCB area is 2 s . The size of the UTCB area limits 
the total number of threads k to 2 a mk < 2 3 . 


m 


UTCB size multiplier. 
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a 


The UTCB location must be aligned to 2°. The total size required for one UTCB is 2 a m. 


Redirector = nilthread 

The current redirector setting for the specified space is not modified. 


Redirector = anythread 

All threads within the specified space are allowed to communicate with any thread in the system. 


Redirector ^ anythread , # nilthread 

All threads within the specified address space are only allowed to send an IPC to a local thread 
or to a thread in the same address space as the specified redirector. All other send operations 
will be deflected to the redirector, the redirected bit (see page 62) in the received message will 
be set, and the IntendedReceiver TCR will indicate the intended receiver of the message. 


control The control field is architecture specific (see Appendix A. 5). It is undefined for some architec- 

tures, but should for reasons of upward compatibility be set to zero. 


Output Parameters 


result The result is 1 if the operation succeeded, otherwise the result is 0 and the ErrorCode TCR 

indicates the failure reason. 


ErrorCode [TCR] Set if result = 0. Undefined if result 5 ^ 0 . 

= 1 No privilege. Current thread does not have privilege to perform operation. 

= 3 Invalid space. The SpaceSpecifier parameter specified an invalid thread ID. 

_ g Invalid UTCB area. Specified UTCB area too small (see UTCB info on page 4) or not within 
user accessible virtual memory region (see Memory Descriptors on page 5). 

_ 7 Invalid KIP area. Specified KIP area too small (see KIP area info on page 4) or not within user 

accessible virtual memory region (see Memory Descriptors on page 5) or KIP area overlaps with 
UTCB area. 


control Delivers the space control value that was effective for the thread when the operation was invoked. 

The value is architecture specific. 


No pagefaults will happen. 


Pagefaults 


System-Call Function: 


Generic Programming Interface 


#include <!4/space.h> 
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Word SpaceControl (Threadld SpaceSpecifier, Word control, Fpage KernellnteifacePageArea, UtcbArea, Threadld 
Redirector, Word& old_Control ) 


Convenience Programming Interface 

Support Functions: 

Word ErrorCode () 

Word ErrNoPrivilege 
Word ErrlnvalidSpace 
Word ErrUtcbArea 
Word ErrKipArea 
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5.1 Messages And Message Registers (MRs) [Virtual Registers] 


Messages can be sent and received through the IPC system call (see page 59). Basically, the sender writes a message 
into the sender’s message registers (MRs) and the receiver reads it from the receiver’s MRs. Each thread has 64 MRs, 
MRo.,. 63 - A message can use some or all MRs to transfer untyped words; it can include memory strings and fpages 
which are also specified using MRs. 

MRs are virtual registers (see page 11), but they are more transient than TCRs. MRs are read-once registers: once 
an MR has been read, its value is undefined until the MR is written again. The send phase of an IPC implicitly reads all 
MRs; the receive phase writes the received message into MRs. 

The read-once property permits to implement MRs not only by special registers or memory locations, but also by 
general registers. Writing to such an MR has to block the corresponding general register for code-generator use; reading 
the MR can release it. Typically, code generated by an IDL compiler will load MRs just before an IPC system call and 
store them to user variables just afterwards. 


Messages 

A message consists of up to 3 sections: the mandatory message tag, followed by an optional untyped-words section, 
followed by an optional typed-items section. The message tag is always held in MR 0 . It contains message control 
information and the message label which can be freely set by the user. The kernel associates no semantics with it. Often, 
the message label is used to encode a request key or to define the method that should be invoked by the message. 


MsgTag [MR 0 ] 


label (16/48) 

flags (4) 

f (6) 

U (B) 


Number of untyped words following word 0. MR i... u hold the untyped words, u = 0 denotes 
a message without untyped words. 


Number of typed-item words following the untyped words or the message tag if no untyped 
words are present. The typed items use MR u +i... u +t. A message without typed items has 
t = 0. 


flags Message flags, see IPC systemcall, page 59. 


label Freely available, often used to specify the request type or invoked method. 


untyped words 

The optional untyped- words section holds arbitrary data that is untyped from the kernel’s point 
of view. The data is simply copied to the receiver. The kernel associates no semantics with it. 


typed items [MR„ + i...„ +i ] 
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The optional typed-items section is a sequence of items such as string items (page 54), map 
items (page 51), and grant items (page 53). Typed message items have their type encoded in the 
lowermost 4 bits of their first word: 


0 hhC 

Stringltem 

see page 54 

100C 

Mapltem 

see page 5 1 

101C 

Grantltem 

see page 53 

lioc 

Reserved 


111 c 

Reserved 



The C bit signals whether the typed item is followed by another typed item ( C = 1) or is the 
last one of the typed-item section (C = 0). The typed items must exactly fit into MR u +i...u+t- 

Note that C and t redundantly describe the message. This is by intention. The C bit allows 
efficient message parsing, whereas t + u can be used to store all MRs of a message to memory 
without parsing the complete message. Upon message sending, the C bits are completely ig- 
nored. The kernel will, however, ensure that the MRs on the receiver side will have the C bits 
set properly. 


Example Messages 


struct (label. Word [2] w) 


Word W2 ( 32 / 64 ) 


Word tui ( 32 / 64 ) 

label (16/48) 

flags 

t = 0 

u = 2 


MR 2 
MR i 
MR 0 


struct (label, Mapltem m) 


Mapltem m 

1000 

label (16/48) 

flags 

t. = 2 

u = 0 


MR i .2 
MR 0 


struct (label. Word w, Stringltem s i, s 2 J 


Stringltem S2 

0 h h 0 

Stringltem s \ 

0 h h 1 

Word W (32/64) 


label (16/48) 

flags 

t = 4 

u = 1 


MR 4,5 


MR 2,3 

MR i 
MR 0 


struct (label. Word [3] w, Mapltem m, Grantltem g, Stringltem s) 
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Stringltem s 

0 h h 0 

Grantltem g 

1011 

Mapltem m 

1001 

Word W 3 ( 32 / 64 ) 


Word W 2 ( 32 / 64 ) 


Word IDl ( 32 / 64 ) 


label (16/48) 

flags 

t = 6 

u = 3 


MR 8,9 

MR 6,7 

MR 4,5 

MR 3 
MR 2 
MR i 
MR 0 


Generic Programming Interface 

The listed generic functions permit user code to access message registers independently of the processor-specific MR 
model. All functions are user-level functions; the microkernel is not involved. 

MsgTag 

#include <l4/ipc.h> 

struct MsgTag { Word raw } 

MsgTag Nil tag 

A message tag with no untyped or typed words, no label, and no flags. 


Bool == ( MsgTag I, r ) 

[IsMsgTagEqual\ 

Bool ! = ( MsgTag I, r) 

Compares all field values of two message tags. 

[IsMsgTagNotEqual] 

Word Label (Msg Tag t) 


Word UntypedWords (Msg Tag t) 


Word TypedWords (Msg Tag t) 

Delivers the message label, number of untyped words, and number of typed words, respectively. 

MsgTag + (MsgTag t, Word label) 

[MsgTagAddLabel] 


MsgTag + = (MsgTag t. Word label ) [MsgTagAddLabelTo] 

Adds a label to a message tag. Old label information is overwritten by the new label. 

MsgTag MsgTag () 

void Set -MsgTag (MsgTag t) 

Delivers/sets MR o. 
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Convenience Programming Interface 

IDL-compiler generated Operations 

IDL code generators are not restricted to the generic interface for accessing MRs. Instead, they can use processor-specific 
methods and thus generate heavily optimized code for MR access. 

However, such processor-specific MR operations are not generally defined and should be used exclusively 
by processor-specific IDL code generators. All other programs must use the operations defined in this 
generic interface. 


Msg 


#include <l4/ipc.h> 
struct Msg { Word raw [64] } 


void Put ( Msg& msg, Word I, int u, Word& [u] ut, int t, { Mapltem ; Grantltem Stringllem} & Items ) [ MsgPut \ 

Loads the specified parameters into the memory object msg. The parameters u and t respectively 
indicate number of untyped words and number of typed words (i.e., the total size of all typed 
items). It is assumed that the msg object is large enough to contain all items. 

void Get ( Msg& msg, Word& ut, {Mapltem, Grantltem, Stringltem}& Items) [ MsgGet \ 

Stores the msg object into the specified parameters. Type consistency between the message in 
the memory object and the specified parameter list is not checked. 

MsgTag MsgTag (Msg& msg) [MsgMsgTag] 

void SetJMsgTag ( Msg& msg, MsgTag t ) [SetJMsgMsgTag] 

Delivers/sets the message tag of the msg object. 


Word Label ( Msg& msg) 

void Set_Label (Msg& msg, Word label) 

Delivers/sets the label of the msg object. 


[MsgLabel] 

[Set_MsgLabel\ 


void Load ( Msg& msg) 

Loads message registers MR o... from the msg object. 


[MsgLoad] 


void Store ( MsgTag t, Msg& msg) [MsgStore] 

Stores the message tag t and the current message beginning with MR i to the memory object 
msg. The number of message registers to be stored is derived from t. 


void Clear ( Msg& msg) 

Empties the msg object (i.e., clears the message tag). 


[MsgClear] 


[MsgAppendWord] 
[ MsgAppendMapItem \ 
[MsgAppendGrantltem] 
[MsgAppendSimpleStringItem\ 


void Append (Msg& msg, Word w) 
void Append (Msg& msg, Mapltem m) 
void Append ( Msg& msg, Grantltem g) 
void Append ( Msg& msg, Stringltem s) 

void Append (Msg& msg, Stringltem& s) [ MsgAppendStringltem ] 

Appends an untyped or a typed item to the msg object. Compound strings must always be 
passed in by reference. A compound string passed by value will be treated as a simple string 
(see page 54). It is assumed that there is enough memory in the msg object to contain the new 
item. 

void Put (Msg & msg. Word u, Word w) [MsgPutWord \ 

Puts an untyped word at untyped word position u (first untyped word has position 0) in the msg 
object. It is assumed that the object contains at least u + 1 untyped words. 


void Put ( Msg& msg, Word t, Mapltem m) 


[ MsgPutMapItem ] 
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void Put 

( Msg& msg, Word t, Grantltem g) 

[MsgPutGrantItem\ 

void Put 

(Msg & msg, Word t, Stringltem s) 

[MsgPutSimplStringltem\ 

void Put 

(Msg& msg, Word t, Stringltem& s) 

[ MsgPutStringltem \ 


Puts a typed item into the msg object, starting at typed word position t (first typed word has 
position 0). Compound strings must always be passed in by reference. A compound string 
passed by value will be treated as a simple string (see page 54). It is assumed that that the object 
has enough typed words to contain the new item. 


Word Get (Msg& msg, Word u) [ MsgWord \ 

void Get ( Msg& msg, Word u, Word& w ) [ MsgGetWord ] 

Delivers the untyped words at position u. It is assumed that the object contains at least u + 1 
untyped words. 


Word Get (Msg & msg, Word t, Mapltem& m) 
Word Get ( Msg& msg, Word t, Grantltem& g) 


[ MsgGetMapItem \ 
[. MsgGetGrantltem \ 


Word Get ( Msg& msg, Word t, Stringltem& s) [MsgGetStringItem\ 

Delivers the typed item starting at typed word position t. It is assumed that the requested item 
is of the right size and type. Returns the size (in words) of the delivered item. 


Low-Level MR Access 

#include <l4/ipc.h> 

void StoreMR (int i, Word& w) 
void LoadMR ( int i, Word w) 

Delivers/sets MR i. 


void StoreMRs (inti,k, Word& [k] w) 

void LoadMRs ( inti,k , Word& [k] w) 

Stores/loads MR i...i+k-i to/from memory. 
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5.2 Mapltem [Data Type] 

An fpage (see page 36) or IO fpage that should be mapped is sent to the mappee as part of a message. A map operation 
is a no-op within the same address space. The fpage is specified by a two-word descriptor: 

MR i+i 
MR j 

access rights rwx The effective access rights for the newly mapped page are calculated by bitwise AND-ing the 
access rights specified in the snd fpage and the access rights that the mapper itself has on that 
fpage. As such, the mapper can restrict the effective access rights but not widen them. 

snd base The sen ^ base specifies the semantics of the map operation if the size of the snd fpage is larger 

or smaller than the window in which the receiver is willing to accept a mapping (see page 57). 
If the size of the snd fpage, 2 s , is larger than the receive window, 2 r , the send base indicates 
which region of the snd fpage is transmitted. More precisely: 

send region = fpage ( addr 3 + 2 r k, 2 r ), for some k > 0 : 

addr s + 2 r k < addr 3 + ( sndbase mod 2 s ) < addr s + 2 r k + 2 r 

and where addr 3 is the base address of the snd fpage. If the size of the snd fpage, 2 s , is smaller 
than the receive window, 2 r , the send base indicates where in the receive window the snd fpage 
is mapped. More precisely: 

receive region = fpage ( addr r + 2 s k, 2 s ), for some k > 0 : 

addr r + 2 s k < addr r + ( sndbase mod 2 r ) < addr r + 2 s k + 2 s 

and where addr r is the base address of the receive window. 

Pages already mapped in the mappee’s address space that would conflict with new mappings are implicitly unmapped 
before new pages are mapped. For performance reasons extension of access rights is possible without prior unmapping, 
iff the very same mapping already exists. This is the case, when 

• the mapper maps from the same address space as the existing mapping; and 

• the mapper maps from the same virtual source address as the existing mapping; and 

• the mapper maps to the same virtual destination address as the existing mapping; and 

• the object (physical address) is the same as the existing mapping. 

Access rights can not be revoked by mapping. The access rights of the resulting mapping are a bitwise OR of the existing 
and the new mapping’s access rights. Access rights are not extended recursively. 

Generic Programming Interface 

#include <l4/ipc.h> 

struct MapItem { Word raw [2] } 

Mapltem MapItem (Fpage f Word SndBase) 

Delivers a map item with the specified fpage and send base. 
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Bool Mapltem (Mapltem m) 

Delivers true if map item is valid. Otherwise delivers false. 

Fpage SndFpage ( Mapltem m) 

Word SndBase ( Mapltem m) 

Delivers fpage/send base of map item. 


[ IsMapItem ] 

[MapItemSndFpage] 

[MapItemSndBase] 
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5.3 Grantltem [Data Type] 


An fpage (see page 36) or IO fpage that should be granted is sent to the mappee as part of a message. It is specified by a 
two-word descriptor: 


snd fpage ( 28 /60) 

Or wx 

snd base / 1024 (22/54) 

°(6) 

101 c 


access rights rwx The effective access rights for the granted page are calculated by bitwise anding the access rights 
specified in the snd fpage and the access rights that the mapper itself has on that fpage. As such, 
the granter can restrict the effective access rights but not widen them. 


snd base The send base specifies the semantics of the map operation if the size of the snd fpage is larger 

or smaller than the window in which the receiver is willing to accept a mapping (see page 57). 
If the size of the snd fpage, 2 s , is larger than the receive window, 2 r , the send base indicates 
which region of the snd fpage is transmitted. More precisely: 

send region = fpage ( addr s + 2 r k, 2 r ), for some k > 0 : 

addr B + 2 r k < addr a + ( sndbase mod 2 s ) < addr s + 2 r k + 2 r 

and where addr 3 is the base address of the snd fpage. If the size of the snd fpage, 2 s , is smaller 
than the receive window, 2 r , the send base indicates where in the receive window the snd fpage 
is mapped. More precisely: 

receive region = fpage ( addr r + 2 s k, 2 s ), for some k > 0 : 

addr r + 2 s k < addr r + ( sndbase mod 2 r ) < addr r + 2 s k + 2 s 

and where addr r is the base address of the receive window. 

Pages already mapped in the grantee’s address space that would conflict with new mappings are implicitly unmapped 
before new pages are mapped. 


Generic Programming Interface 

#include <l4/ipc.h> 

struct GrantItem { Word raw[2] } 

Grantltem GrantItem (Fpage f Word SndBase ) 

Delivers a grant item with the specified fpage and send base. 

Bool Grantltem (Grantltem g ) [ IsGrantltem \ 

Delivers true if grant item is valid. Otherwise delivers false. 

Fpage SndFpage (Grantltem g) [GrantltemSndFpage] 

Word SndBase (Grantltem g) [GrantltemSndBase] 

Delivers fpage/send base of grant item. 
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5.4 Stringltem [Data Type] 

A string item specifies a sequence of bytes in user space. No alignment is required, the maximal string size is 4 MB. In 
send messages, such a string is copied to the receiver buffer when transferring the message. String items are also used to 
specify receive buffers in buffer registers on the receiver’s side. 


Simple String 

A simple string is a contiguous sequence of bytes. 


string ptr (32 /64) 

string length ( 22 / 54 ) 

0 

0 (5) 

0 hhC 


MR, + i 

MR; 


string ptr The start address of the string to be sent or the start address of the buffer for receiving a string (no 

alignment restrictions). However, the string/buffer must fit entirely into the legally addressable 
user space. 


string length The length of the string to be sent or the size of the receive buffer. In the second case, strings 
up to (including) this length can be received. Maximum string length is 4 M bytes, even if the 
according field is 54 bits wide on 64-bit processors. 

1 . ^ Cacheability hint. Except for hh = 00, the semantics of this parameter depends on the processor 

type (see Appendices A.6 and B.5). 

^ _ qq Use the processor’s default cacheability strategy. Typically, cache lines are allocated for data 
read and written (assuming that the processor’s default strategy is write-back and write-allocate). 


Compound String 

A compound string is a noncontiguous string that consists of multiple contiguous substrings which can be scattered 
around the entire user address space. The substrings must not overlap. For send and receive IPC operations, a compound 
string is handled as a single logical string. When sending such a string through IPC, the substrings are transferred as if 
they were one contiguous string (gather). On the receiver side, a compound string buffer is treated as one logical buffer. 
The corresponding received string is scattered among the compound buffer’s substrings. 

A compound string can be specified as a sequence of substrings where each substring has the form of a simple string 
except that the continuation flag c is set for all but the last substring. If j subsequent substrings have the same size, e.g., 
for equally sized buffers, a single length word can be used for all j substrings so that only j + 1 words instead of 2 j 
words are required. 


length word 





substring length ( 22 / 54 ) 

c 

j - 1 (5) 

0 hhC 


The type information 0 hhC is only required for the first word of a string descriptor. The field is 
ignored for further length words in a compound-string descriptor. 

j Number of subsequent string-ptr words. These string ptrs specify j substrings that have all the 

same substring length. 

c = 0 Continuation flag reset. The compound string descriptor ends with the j th string ptr word fol- 
lowing the current length word. 

c _ -| Continuation flag set. The current length word and j string-ptr words are followed by (at least) 
one substring descriptor, i.e., another length word, etc. 
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Example 


substrings ptr (32 / 6 4) 


substring i+ i length (22/54) 0 0 


substring/ ptr ( 32 / 6 4) 


( 5 ) 


0 


( 4 ) 


MR.+J+2 

MRi+j+t 

MRj + j 


substringi ptr ( 32 /64) 

substringi.../ length (22/54) 

1 

3 ~ 1 ( 5 ) 

0 hhC 


MRi+i 


MR; 


Generic Programming Interface 


#include <l4/ipc.h> 

struct StringItem {Word raw [*] } 


Bool StringItem ( Stringltem& s) [ IsStringltem \ 

Delivers true if string item is valid. Otherwise delivers false. 

Bool CompundString (Stringltem& s) 

Delivers the c-flag value (true = set). 

Word Substrings ( Stringltem& .s) 

void* Substring ( Stringltem& s. Word n) 

Delivers number of substrings/address of nth substring. 

StringItem StringItem (int size, void* address) 

Delivers a simple string item with the specified size and location. 

(Stringltem& dest, StringItem AdditionalSubstring) [ AddSubstringTo ] 

Append substring to the string item. It is assumed that there is enough memory in the string item 
to contain the new substring. 

(Stringltem& dest, void * AdditionalSubstringAddress) [ AddSubstringAddressTo ] 

Append a new substring pointer to the string item. It is assumed that there is enough memory in 
the string item to contain the new substring pointer. 


StringItem & + = 


StringItem & + = 


Convenience Programming Interface 

Support Functions: 

#include <l4/ipc.h> 

struct CacheAllocationHint { Word raw } 


CacheAllocationHint UseDefauItCacheLineAIIocation 
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Bool == ( CacheAllocationHint 1 r) [ IsCacheAllocationHintEqual ] 

Bool ! = (CacheAllocationHint l, r) [IsCacheAllocationHintNotEqual] 

Compares two cache allocation hints. 

CacheAllocationHint CacheAllocationHint (Stringltem s) 

Delivers the cache allocation hint of the string item. 

Stringltem + (Stringltem s, CacheAllocationHint h) [ AddCacheAllocationHint \ 

Stringltem + = (Stringltem s, CacheAllocationHint h) [AddCacheAllocationHintTo] 

Adds a cache allocation hint to a string item. An already existing hint is overwritten. 
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5.5 String Buffers And Buffer Registers (BRs) [Pseudo Registers] 


For receiving messages that contain string items, the receiver has to specify appropriate string buffers. Such buffers are 
described by string items (see page 54). A buffer can be contiguous (simple string) or non-contiguous (compound string). 

Such buffer descriptors are held in 33 per-thread Buffer Registers BR 0 ... 32 . The number of buffer registers is sufficient 
to specify, for example, one compound buffer of 31 equally-sized sub-buffers. Up to 16 buffers can be specified provided 
that not more than 33 BRs are required. 

When a message is received, the first message string item is copied into the first buffer string item which starts at BR 1 ; 
the next message string item is copied to the next buffer string item, etc. The list of buffer strings is terminated by having 
the C bit in the item type specifier of the last string zeroed. 

BRs are registers in the sense that they are per-thread objects and can only be addressed directly, not indirectly through 
pointers. BRs are static objects like TCRs. i.e., they keep their values until explicitly modified. BRs can be mapped to 
either special registers or to memory locations. 






Acceptor [BR 0 ] 

RcvWindow (28/60) 

000s 


RcvWindow 

s 

BR 0 specifies which typed items are accepted when a message is received. 

Fpage (without access bits) that specifies the address-space window in which mappings and 
grants are accepted. Nilpage denies any mapping or granting; CompleteAddressSpace accepts 
any mapping or granting. 

Stringltems are accepted iff s = 1. 

buffer string items 

[BRr...] 

contain the valid buffer string items. Ignored if s — 0 in BR 0 . 




Generic Programming Interface 

The listed generic functions permit user code to access buffer registers independently of the processor-specific BR model. 
All functions are user-level functions; the microkernel is not involved. 


Acceptor 

#include <l4/ipc.h> 


struct Acceptor { Word raw } 

Acceptor UntypedWords Acceptor 
Acceptor StringltemsAcceptor 

Acceptor MapGrantltems ( Fpage RcvWindow ) 

Delivers an acceptor which allows untyped words, string items, or mappings and grants. 


Acceptor + (Acceptor 1, r) [ AddAcceptor ] 

Acceptor + = ( Acceptor l, r) [AddAcceptorTo] 

Adds mappings/grants or string items to an acceptor. Adding a non-nil receive window will 
replace an existing window. 


Acceptor — (Acceptor 1, r ) [ RemoveAcceptor ] 

Acceptor — = (Acceptor l, r) [RemoveAcceptorFrom\ 

Removes mappings/grants or string items from an acceptor. Removing a non-nil receive window 
will deny all mappings or grants, regardless of the size of the receive window. 
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Bool Stringltems (Acceptor a) [ HasStringltems ] 

Boo I MapGrantltems ( Acceptor a) [HasMapGrantltems] 

Checks whether string items/mappings are allowed. 

Fpage RcvWindow (Acceptor a) 

Delivers the address space window where mappings and grants are accepted. Delivers nilpage 
if mappings or grants are not allowed. 

void Accept (Acceptor a) 

Sets BRo. 

void Accept ( Acceptor a, MsgBuffer& b) [AcceptStrings] 

Sets BRo and loads the buffer description b into BR i. .. 

Acceptor Accepted () 

Delivers BR o. 


Convenience Programming Interface 

MsgBuffer 

#include <l4/ipc.h> 

struct MsgBuffer { Word raw [32] } 


void Clear ( MsgBuffer& b) [MsgBufferClear] 

Clears the message buffer (i.e., inserts a single empty string into it). 

void Append ( MsgBuffer& b, Stringltem s ) [ MsgBufferAppendSimpleRcvString ] 

void Append (MsgBuffer& b, Stringltem * s) [MsgBufferAppendRcvString] 

Appends a string buffer to the message buffer. Compound strings must always be passed in by 
reference. A compound string passed by value will be treated as a simple string. It is assumed 
that there is enough memory in the message buffer object to contain the new string buffer. 


Low-Level BR Access 

#include <l4/ipc.h> 

void StoreBR (int i, Word& w) 
void LoadBR ( int i. Word w ) 

Delivers/sets the value of BR 

void StoreBRs (inti, k, Word& [k]) 

void LoadBRs (inti, k, Word& [k]) 

Stores/loads BR i...i+k- 1 to/from memory. 


Code generators of IDL and other compilers are not restricted to the generic interface. They can use any processor-specific 
methods and optimizations to access BRs. 



IPC 


59 


5.6 IPC [Systemcall] 


Threadld to > Threcidld from 

Threadld FromSpecifier 
Word Timeouts 


IPC is the fundamental operation for inter-process communication and synchronization. It can be used for intra- and 
inter-address-space communication. All communication is synchronous and unbuffered: a message is transferred from 
the sender to the recipient if and only if the recipient has invoked a corresponding IPC operation. The sender blocks until 
this happens or until a period specified by the sender has elapsed without the destination becoming ready to receive. 

IPC can be used to copy data as well as to map or grant fpages from the sender to the recipient. For the description of 
messages see page 46. A single IPC call combines an optional send phase and an optional receive phase. Which phases 
are included is determined by the parameters to and FromSpecifier. Transitions between send phase and receive phase are 
atomic. 

Ipc operations are also controlled by MRs, BRs and some TCRs. RcvTimeout and SndTimeout are directly specified 
as system-call parameters. Each timeout can be 0, oo (i.e., never expire), relative or absolute. For details on timeouts see 
page 28. 


Variants 

To enable implementation-specific optimizations, there exist two variants of the IPC system call. Functionally, both 
variants are identical. Transparently to the user, a kernel implementation can unify both variants or implement differently 
optimized functions. 


IPC Default IPC function. Must always be used except if all criteria for using LlPC are fulfilled. 

Ljpj-. IPC function that may be optimized for sending messages to local threads. Should be used 

whenever it is absolutely clear that in the overwhelming majority of all invocations 

• a send phase is included; and 

• the destination thread is specified as a local thread ID; and 

• a receive phase is included; and 

• the destination thread runs on the same processor; and 

• the RcvTimeout is oo, and 

• the IPC includes no map/grant operations. 


Input Parameters 


to = nilthread IPC includes no send phase. 

to nilthread Destination thread; IPC includes a send phase 


FromSpecifier = nilthread 

IPC includes no receive phase. 
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FromSpecifier = anythread 

IPC includes a receive phase. Incoming messages are accepted from any thread (including 
hardware interrupts). 

FromSpecifier = anylocaltliread 

IPC includes a receive phase. Incoming messages are accepted from any thread that resides in 
the current address space. 

FromSpecifier -A nilthread, # anythread, A anylocaltliread 

Ipc includes a receive phase. Incoming messages are accepted only from the specified thread. 
(Note that hardware interrupts can be specified.) 


Timeouts 


SndTimeout , | 6 ) 


RcvTimeout 16 j 


RcvTimeout 


SndTimeout 


The receive phase waits until either a message transfer starts or the RcvTimeout expires. Ignored 
for send-only IPC operations. 

For relative receive timeout values, the receive timeout starts to run after the send phase has 
successfully completed. If the receive timeout expires before the message transfer has been 
started IPC fails with “receive timeout”. A pending incoming message is received if the timeout 
period is 0. 

If the send timeout expires before the message transfer could start the IPC operation fails with 
“send timeout”. A send timeout of 0 ensures that IPC happens only if the addressed receiver is 
ready to receive when the send IPC operation is invoked. Otherwise, IPC fails immediately, i.e., 
without blocking. 


MsgTag [MR 0 ] 


label (16/48) 

°(3) 

P 

* (6) 

U (6) 


Message head of the message to be sent. Only the upper 16/48 bits are freely available. The 
lower 16 bits hold the SndControl parameter. It describes the message to be sent and contains 
some control bits; ignored if no send phase. 

u Number of untyped words following word 0. MR i...„ hold the untyped words, u = 0 denotes 

a message with no untyped words. 

r Number of words holding typed items that follow the untyped words (or the message tag if no 

untyped words are present). The typed items use MR u +i and following MRs, potentially up to 
MR 63 . t = 0 denotes a message without typed items. 

p=0 Normal (unpropagated) send operation. The recipient gets the original sender's id. 

p= 1 Propagating send operation. The VirtualSender TCR specifies the id of the originator thread. 

(i.e., the thread to send the message on behalf of). If originator thread and current sender, or 
current sender and receiver reside in the same address space, propagation is always permitted. 
Otherwise, IPC occurs unpropagated. Propagation is also allowed if the originator thread is an 
interrupt thread waiting (closed) for the current thread, or if the current sender is a redirector 
for the originator thread (or there exists a chain of redirectors from the originator to the current 
sender). 

If propagation is permitted, the receiver receives the originator's id instead of the current sender’s 
id, the/? bit in the receiver’s MsgTag is set, and the current sender's id is stored in the receiver’s 
ActualSender TCR. If the originator thread is waiting (closed) for a reply from the current sender, 
the originator’s state is additionally modified so that it now waits for the new receiver instead of 
the current sender. 

label Freely available, often used to specify the request type or invoked method, respectively. 

[MRi...„] Untyped words to be sent. Ignored if no send phase. 

[MR ■u+i ...u+t] Typed items to be sent. Ignored if no send phase. 
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XferTimeouts [TCR] 


XferTimeout Snd (16 ) 


XferTimeout Rev (i 6 ) 


Once a message transfer has been started, the time for transferring the message is roughly 
bounded by the minimum of sender’s and receiver’s XferTimeout. “Roughly” means that xfer 
timeouts are only checked when message copy raises a pagefault in the sender’s or in the re- 
ceiver’s address space. Copying data and mapping/granting is assumed to take no time. A 
relative transfer timeout always refers to the beginning of the message transfer (actually when 
the first page fault is raised). Logically, at that point it is transferred into an absolute timeout 
which then is used as send and receive timeout for the first and all subsequent page-fault RPCs 
in the message transfer. 

If the effective transfer timeout expires during the message transfer, IPC fails with “xfer timeout” 
(on both sides). Additional information specifies whether the page fault was in the receiver’s or 
in the sender’s address space and which part of the message was already transferred. Each thread 
has two transfer timeouts. One for the send phase and one for the receive phase. 


Acceptor [BR 0 ] 


RcvWindow ( 2 8 / 60 ) 


000s 


BR o specifies which typed items are accepted when a message is received. 


RcvWindow Fpage (without access bits) that specifies the address-space window in which mappings and 

grants are accepted. Nilpage denies any mapping or granting; CompleteAddressSpace accepts 
any mapping or granting. 


s 


Stringltems are accepted iff s = 1. 


buffer string items [BRi . . . ] 

contain the valid buffer string items. Ignored if s = 0 in BR o. 


Output Parameters 


from Thread ID of the sender from which the IPC was received. Thread IDs are delivered as local 

thread IDs iff they identify a thread executing in the same address space as the current thread. It 
does not matter whether the sender specified the destination as local or global id. 

Only defined for IPC operations that include a receive phase. 


MsgTag [MR 0 ] 


label ( 16 / 48 ) 

E X rp 

t(6) 

u (6) 


If the IPC operation included a receive phase. MR o contains the message tag of the received 
message. The upper 16/48 bits contain the user-specified label. The lower bits describe the 
received message, contain the error indicator, and the cross-processor IPC indicator. 

MR o is defined even if the IPC operation did not include a receive phase. In the send-only case, 
MR o returns the error indicator. 

Number of untyped words following word 0. it = 0 means no untyped words. For IPC opera- 
tions without receive phase, u = 0 is delivered. 

Number of received words that hold typed items, t = 0 means no typed items. For IPC opera- 
tions without receive phase, t = 0 is delivered. 

Propagated IPC. If reset (p — 0) the IPC was not propagated. If set (p — 1) the IPC was propa- 
gated and the FromSpecifier indicates the originator thread's id. The ActualSender specifies the 
id of the thread which performed the propagation. 
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r 

X 

E 

label 

[MRi ...„] 

[IMR^ -|_ 1 . . . u -|_fc ] 

ErrorCode [TCR] 


P 

errors 1, 2,3 

e = 1 

e = 2 

e = 3 

errors 4, 5, 6, 7 

offset 

e = 4 


Redirected IPC. If reset (r = 0) the IPC was not a redirected one. If set (r = 1) the IPC was 
redirected to the current thread, and the IntendedReceiver TCR specifies the id of the thread 
supposed to receive the message. 

Cross-processor IPC. If reset (X = 0) the received IPC came from a thread running on the 
same processor as the receiver. If set (X = 1) the received IPC was cross-processor. For IPC 
operations without receive phase, X = 0 is delivered. 

Error indicator. If reset (E = 0) the IPC operation terminated successful. 

If set (E = 1) IPC failed. If the send phase was successful but a receive timeout occurred 
afterwards, or if a message could only be partially transferred, the entire IPC fails. The error 
code and additional information can be retrieved from the ErrorCode TCR. The fields label, t, 
and it are valid if the error code signals a partially received message. 

Label of the received message. For IPC operations without receive phase, the label is 0. 

Untyped words that have been received. Undefined if no receive phase. 

Typed items that have been received. Undefined if no receive phase. 


x ( 28 / 56 ) 


: ( 3 ) 


Only defined if the error indicator E in MR o is set. IPC failed, i.e., was not correctly completed. 
The x field depends on the error code, see below. The p field specifies whether the error occurred 
during send or receive phase. If the error occurred during the receive phase the send phase (if 
any) was completed successfully before. If the error occurred during the send phase, the receive 
phase (if any) was skipped. 

Specifies whether the error occurred during the send phase (p = 0) or the receive phase (p = 1). 


( 28 / 60 ) 


(3) 


\P 


Error happened before a partner thread was involved in the message transfer. Therefore, the 
error is signaled only to the thread that invoked the failing IPC operation. 

Timeout. 

From is undefined in this case. 

Non-existing partner. If the error occurred in the send phase, to does not exist. ( Anythread as 
a destination is illegal and will also raise this error.) If the error occurred in the receive phase, 
FromSpecifier does not exist. (FromSpecifier = anythread is legal, and thus will never raise this 
error.) 

Canceled by another thread (system call exchange registers ). 


offset 


( 28 / 60 ) 


(3) 


\P 


A partner thread is already involved in the IPC operation, and the error is therefore signaled to 
both threads. 

The message transfer has been started and could not be completed. The offset identifies exactly 
the number of bytes that have been been transferred successfully so far through string items. 

Message Overflow. 

A message overflow can occur (1) if a receiving buffer string is too short, (2) if not enough 
buffer string items are present, and (4) if a map/grant of an fpage fails because the system has 
not enough page-table space available. The offset in conjunction with the received MRs permits 
sender and receiver to exactly determine the reason. 


e = 5 


Xfer timeout during page fault in the invoker’s address space. 
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e = 6 Xfer timeout during page fault in the partner’s address space, 
e = 7 Aborted by another thread (system call exchange registers ). 


Pagefaults 

Three different types of pagefault can occur during ipc: pre-send. post-receive, and xfer pagefaults. Only xfer pagefault 
are critical from a security point of view. Fortunately, messages without strings will never raise xfer pagefaults and need 
thus no special pagefault provisions: 

Pre-send pagefaults 

happen in the sender's context before the message transfer has really started. The destination 
thread is not involved; in particular, it is not locked. Therefore, the destination thread might 
receive another message or time out while the sender’s pre-send pagefault is handled. Send and 
transfer timeouts do not control pre-send pagefaults. Pre-send pagefaults are uncritical from a 
security point of view, since only the sender’s own pager is involved and only the sender could 
suffer from its potential misbehavior. 

Post-receive pagefaults 

happen in the receiver’s context after the message has been transferred. The sender thread is no 
longer involved, especially, it is no longer locked. Consequently, post-receive pagefault are not 
subject to send and transfer timeouts. Like pre-send pagefaults, post-receive pagefaults are also 
uncritical from a security perspective since only the receiver and its pager are involved. 


Xfer pagefaults happen while the message is being transferred and both sender and receiver are involved. There- 
fore, xfer pagefaults are critical from a security perspective: If such a pagefault occurs in the 
receiver’s space, the sender may be starved by a malicious receiver pager. An xfer pagefault in 
the sender’s space and a malicious sender pager may starve the receiver. As such, xfer pagefaults 
are controlled by the minimum of sender’s and receiver’s xfer timeouts. 

However, xfer pagefaults can only happen when transferring strings. Send mes- 
sages without strings or receive buffers without receive string buffers are guar- 
anteed not to raise xfer pagefaults. 


Generic Programming Interface 

System-Call Function: 

#include <l4/ipc.h> 

MsgTag Ipc (Threadld to, FromSpecifier, Word Timeouts, Threadld& from) 
MsgTag Lipc (Threadld to, FromSpecifier, Word Timeouts, Threadld& from) 


Note that message registers have read-once semantics and that returning the message tag implies reading MRo. The 
contents of the message tag is therefore lost if the application does not implicitly store the return value of IPC or LlPC . 


Derived Functions: 

#include <!4/ipc.h> 


Convenience Programming Interface 


MsgTag Call ( Threadld to) 

{ Call (to, never, never) } 
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MsgTag Call ( Threadld to, Time SndTimeout, RcvTimeout ) 

{ Ipc (to, to. Timeouts (SndTimeout, RcvTimeout), -) } 

MsgTag Send (Threadld to) 

{ Send (to, never) } 

MsgTag Send (Threadld to, Time SndTimeout) 

{ Ipc (to, nilthread. Timeouts (SndTimeout. -), -) } 

MsgTag Reply ( Threadld to) 

{ Send (to, ZeroTime) } 

MsgTag Receive (Threadld from) 

{ Receive (from, never) } 

MsgTag Receive (Threadld from, Time RcvTimeout) 

{ Ipc (nilthread, from. Timeouts (-, RcvTimeout), -) } 

MsgTag Wait (Threadld& from) 

{ Wait (never, from) } 

MsgTag Wait (Time RcvTimeout, Threadld& from) 

{ Ipc (nilthread, anythread. Timeouts (-, RcvTimeout), from) } 

MsgTag Reply Wait (Threadld to, Threadld & from) 

{ ReplyWait (to. never, from) } 

MsgTag ReplyWait (Threadld to, Time RcvTimeout, Threadld & from) 

{ Ipc (to, anythread. Timeouts (TimePeriod(O), RcvTimeout), from) } 

void Sleep (Time t) 

{ Set JVIsgTag (Receive (MyLocalld, t)) } 

MsgTag Lcall (Threadld to) 

{ Lipc (to, to. Timeouts (never, never), -) } 

MsgTag LreplyWait (Threadld to, Threadld & from) 

{ Lipc (to, anylocalthread, Timeouts (TimePeriod (0), never), from) } 


Support Functions: 

#include <l4/ipc.h> 

Boo l IpcSucceeded (Msg Tag t) 

Bool IpcFailed (Msg Tag t) 

Delivers the state of the error indicator (the E bit of MR o). 

Bool IpcPropagated (Msg Tag t) 

Bool lpcRedirected (Msg Tag t) 

Bool IpcXcpu (Msg Tag t) 

Checks if the IPC was propagated/redirected/cross cpu. 

Word ErrorCode () 

Threadld IntendedReceiver () 


[Call -Timeouts] 


[Send TTime out] 


[Receive -Timeout] 


[Wait -Timeout] 


[ReplyWait -Timeout] 
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Threadld ActualSender () 

Delivers the error code/intended receiver TCR/actual sender. 

void Set .Propagation ( Msg& Tag t) 

Sets the propagation bit. 

void Set .Virtual Sender ( Threadld t) 

Sets the virtual sender TCR. 

Word Timeouts (Time SndTimeout, RcvTimeout ) 

Delivers a word containing both timeout values. 
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EXCEPTIONHANDLER 


6.1 ExceptionHandler [tcr] 


An exception handler thread can be installed to receive exception IPCs. 


ExceptionHandler 

^nilthread specifies the exception handler thread. When a thread raises an exception the kernel sends an 

exception IPC message on the thread’s behalf to the thread’s exception handler thread and waits 
for a response from the exception handler containing the instruction pointer where the thread 
should continue execution in MRi. The format of the exception IPC message is architecture 
specific. 

The architectural registers of the faulting thread, BRo, TCRs, and the MRs containing the ex- 
ception message are preserved. 

=nilthread No exception handler is specified. If an exception is raised the thread is halted and not scheduled 

anymore, nilthread is the default value for newly created threads. 


Generic Programming Interface 

#include <l4/thread.h> 

Threadld ExceptionHandler () 

void Set .ExceptionHandler (Threadld new) 

Delivers/sets the exception handler TCR. 
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6.2 Cop Flags [tcr] 


The coprocessor flags TCR helps the kernel to optimize thread switching for some hardware architectures. 


Cop Flags 


C7 . . . CQ 


By resetting a Ci-bit to 0. a thread tells the system that it no longer needs coprocessor i. If the 
kernel finds a = 0, it concludes that registers and state of coprocessor i do not have to be saved. 
However, the kernel ensures that the coprocessor can not be used as a covert channel between 
different address spaces. 

Once a thread has reset bit a it must set a to 1 before it issues the next operation on coprocessor 
i. Otherwise, coprocessor registers and state might be arbitrarily modified while using it. 

Note that the Ci-bits are write-only. Reading them results in an undefined value. Upon thread 
creation, all Ci-bits are set to 1. 


Generic Programming Interface 

#include <l4/thread.h> 

void SetjCopFlag (Word n) 

void Clr_CopFlag (Word n) 

Sets/clears coprocessor flag c n . 
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6.3 PROCESSORCONTROL [Privileged Systemcall] 

Word ProcessorNo > Word result 

Word InternalFrequency 
Word ExternalFrequency 
Word voltage 

Control the internal frequency, external frequency, or voltage for a system processor. 


Input Parameters 


ProcessorNo Specifies the processor to control. Number must be a valid index into the processor descriptor 

array (see Kernel Interface Page, page 4). 

All further input parameters have no effect if the supplied value is —1, ensuring that the corresponding value is not 
modified. The following description always refers to values ^ — 1. 


InternalFrequency Sets internal frequency for processor to the given value (in kHz). 


ExternalFrequency 

Sets external frequency for processor to the given value (in kHz). 


voltage Sets voltage for processor to the given value (in mV). A value of 0 shuts down the processor. 


Output Parameters 


result The result is 1 if the operation succeeded, otherwise the result is 0 and the ErrorCode TCR 

indicates the failure reason. 


ErrorCode [TCR] Set if result = 0. Undefined if result ^0. 

= 1 No privilege. Current thread does not have privilege to perform operation. 

Note that the active internal and external frequency of all processors are available to all threads via the kernel interface 
page. 


Pagefaults 

No pagefaults will happen. 
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Generic Programming Interface 

System-Call Function: 

#include <l4/misc.h> 

Word ProcessorControl ( Word ProcessorNo, control InternalFrequency, ExtemalFrequency, voltage) 


Convenience Programming Interface 

Support Functions: 

Word ErrorCode () 

Word ErrNoPrivilege 
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6.4 MemoryControl [Privileged Systemcall] 


Word control > Word result 

Word attributed 
Word attribute 1 
Word attribute 2 
Word attribute^ 


Set the page attributes of the fpages (MR 0 ...k) to the attribute specified with the fpage. 


Input Parameters 


control 


0 (26/58) 


k (6) 


Specifies the highest MR u that holds an fpage to set the attributes. The number of fpages is thus 

k + 1 . 


attribute ,■ Specifies the attribute to associate with an fpage. The semantics of the attributei values are 

hardware specific, except for the value 0 which specifies default semantics. 


FpageList MR 0 ...k Fpages to be processed. 


Fpage MR i 


fp a g e (28/60) 


00b (2) 


Fpage to change the attributes. A nilpage specifies a no-op. 
a selects attribute a to be set as the fpages memory attributes. 


Output Parameters 


result The result is 1 if the operation succeeded, otherwise the result is 0 and the ErrorCode TCR 

indicates the failure reason. 


ErrorCode [TCR] Set if result = 0. Undefined if result ^0. 

= 1 No privilege. Current thread does not have privilege to perform operation. 

= 5 Invalid parameter. Invalid or unsupported memory attribute. 


No pagefaults will happen. 


Pagefaults 
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Generic Programming Interface 

System-Call Function: 

#include <l4/misc.h> 

Word MemoryControl (Word control, Word& attribute s[4]) 


Word DefaultMemory 


Convenience Programming Interface 

Derived Functions: 

#include <l4/misc.h> 

Word Set _Page Attribute (Fpagef Word attribute) 

{ Word attributes [4]; attributes[0] = attribute; Set_Rights(f, 0); LoadMR (0, f); 
MemoryControl (0, &attributes); } 

Word SetJPagesAttributes (Word n, Fpage& [n] fpages, Word& [4] attributes) 

{ LoadMRs (0, n , fpages); MemoryControl (n — 1, attributes); } 


Support Functions: 

Word ErrorCode () 
Word ErrNoPrivilege 
Word ErrlnvalidParam 
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THREAD START PROTOCOL 


7.1 Thread Start Protocol [Protocol] 

Newly created active threads start immediately by receiving a message from its pager. The received message contains the 
initial instruction-pointer and stack-pointer for the thread. 


MR 2 
MR i 
MR 0 


From Pager 


Initial SP ( 32 /64) 


Initial IP (32/64) 


0 ( 16 / 48 ) 


1 ( 4 ) 


t = 0 


(6) 


u = 2 


( 6 ) 
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7.2 Interrupt Protocol [Protocol] 

Interrupts are delivered as an IPC call to the interrupt handler thread (i.e.. the pager of the interrupt thread). The interrupt 
is disabled until the interrupt handler sends a re-enable message. 


From Interrupt Thread 

MR 0 


To Interrupt Thread 

MR 0 
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7.3 Pagefault Protocol [Protocol] 


A thread generating a pagefault will cause the kernel to transparently generate a pagefault IPC to the faulting thread's 
pager. The behavior of the faulting thread is undefined if the pager does not exactly follow this protocol. 


To Pager 


faulting user-level IP ( 32 / 64 ) 


fault address ( 32 / 64 ) 


(12/44) 


0 rwx 


1 (4) 


t = 0 


(6) 


u = 2 


(6) 


MR 2 
MR 1 
MR 0 


rwx 


The rwx bits specify the fault reason: 


r read fault 
w write fault 
x execute fault 

A bit set to one reports the type of the attempted access. On processors that do not differentiate 
between read and execute accesses, x is never set. Read and execute accesses will both be 
reported by the r bit. 


Acceptor [BR 0 ] 


0 (22/54) 


s = 1 ( 6) 0 00 0 


BR 0 


The acceptor covers the complete user address space. The kernel accepts mappings or grants 
into this region on behalf of the faulting thread. The received message is discarded. 


Front Pager 


Mapltem / Grantltem 


0 (16/48) 

0 (4) 

t — 2 (6) 

U = 0 ( 6 ) 


MR 1,2 

MR 0 
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7.4 Preemption Protocol [Protocol] 


From Preempted Thread 

MR 2 
MR i 
MR 0 

The preemption message contains the system clock when the thread was preempted. The pre- 
emption message is sent with relative timeout 0. If the message can not be delivered (e.g.. due 
to timeouts) the message is dropped. 


Clock /2(3 2 /64) (32/g4) 


Clock mod2 (32 / 64 ) ( 32 / 64 ) 


~3 ( 12 / 44 ) 

0 (4) 

0 (4) 

t — 0 (6) 

U = 2 (6) 
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7.5 Exception Protocol [Protocol] 

The exception IPC contains a label, the faulting instruction pointer, and additional architecture specific exception words. 
The reply from the exception handler contains a label, an instruction pointer where the faulting thread is resumed, and an 
optional number of additional architecture specific words. 

Note that the stack pointer is not explicitly specified to allow architecture specific optimizations. 


To Exception Handler 


exception word k _ 1 ( 32 / 64 ) 


exception word o ( 32 / 64 ) 


IP (32/64) 


label ( 12 / 44 ) 

0 (4) 

0 (4) 

t = 0 (6) 

CO 

II 

3 


MR k+i 


MR 2 
MR 1 
MR 0 


k Number of exception words. 

label specifies the exception type, 

= — 4 System exceptions are defined for all architectures. 
= — 5 Architecture specific exceptions. 


From Exception Handler 


exception reply word k —\ (32/64) 


MR fc+i 


exception reply word 0 ( 3 2/64) 


0 (16/48) 


IP (32/64) 


1 (4) 


t = 0 


(6) 


u = k 


( 6 ) 


MR 2 
MRi 
MR 0 


k 


Number of exception reply words. 


IP 


Location where execution is resumed in the faulting thread. 
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7.6 SigmaO RPC protocol [Protocol] 


<to is the initial address space. Although it is not part of the kernel, its basic protocol is defined with the kernel. Specific 
<To implementations may extend this protocol. 

The address space a o is idempotent, i.e., all virtual addresses in this address space are identical to the corresponding 
physical address. Note that pages requested from o o continue to be mapped idempotently if the receiver specifies its 
complete address space as receive fpage. 

< 7 o gives pages to the kernel and to arbitrary tasks, but only once. The idea is that all pagers request the memory they 
need in the startup phase of the system so that afterwards o o has exhausted all its memory. Further requests will then 
automatically be denied. 


Kernel Protocol 


To a 0 


(32/64) 


requested fpage ( 32 / 64 ) 


^6 (12/44) 


'(4) 


1 (4) 


f = 0 


(6) 


u = 2 


(6) 


MR 2 
MR i 
MR o 


requested fpage 


(22/54) 


S (6) 


Orvux 


s _ q Kernel requests the amount of memory recommended by <7o for kernel use (pagetable and other 
kernel-internal data). 

s ^ q Kernel requests an fpage of size 2 s . The fpage can be located at an arbitrary position but must 
contain ordinary memory. If a free fpage of size 2 s is available, it is granted to the kernel. 

rwx The rwx bits are ignored, a o always grants fpages with maximum access rights to the kernel. 


From a o 

Kernel memory recommendation 

MR 2 
MRi 
MR 0 


0 (32/64) 


amount 

(32/64) 



0 (16/48) 

°(4) 

t — 0 (6) 

U = 2 (6) 


amount Amount of memory recommended for kernel use (in bytes). 


Grant Response 


Grantltem 



o (16/48) 

0 (4) 

f = 2 (6) 

« = 0 (g) 


MR i ]2 

MR o 
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Grant Reject 


nilpage ( 32 / 64 ) 

0 (28/60) 


0 (16/48) 

0 (4) 

* “ 2 (6) 



MR 2 
MR i 
MR o 


User Protocol 


To a 0 


requested attributes ( 32 / 64 ) 


requested fpage ( 32 / 64 ) 


(12/44) 

0 (4) 

0 (4) 

t = 0 (6) 

u = 2 (6) 


MR 2 
MR 1 
MR 0 


requested fpage 


b/2 10 (22/54) 


S (6) 


Orwx 


(To deals with fpages of arbitrary size. A successful response from op contains an fpage of 
physically contiguous memory. 


1 ) ^ _ 1 Requests the specific fpage with base address b and size 2 s . If the fpage is neither owned by the 
kernel nor by a user thread (not even partially), the requested fpage is mapped to the requestor’s 
address space and the fpage is marked as owned by the requesting thread (i.e., fpage is not 
marked as being owned by the address space in which thread resides). Fpages belonging to 
dedicated-memory (see page 85) can be requested. If the requested fpage is already owned by 
the requestor only the page attributes are modified. No new mapping operations happens. 


5 — _ i Requests an fpage of size 2 s but with arbitrary address. If a free fpage of size 2 s is available, 
it is mapped to the requestor’s address space and marked as owned by the requesting thread 
(i.e., fpage is not marked as being owned by the address space in which thread resides), o o 
is free to use the requested-attribute for choosing a best fitting page. Fpages belonging to 
dedicated-memory (see page 85) are not considered to be free and will not be delivered upon 
such anonymous requests. No new mapping operations happens. 


rwx The rwx bits are ignored. oo always maps fpages with maximum access rights to the requestor. 


requested attributes 


= 0 The page is requested with default attributes. 

# 0 The page is requested with some architecture dependent attributes. 


From (T 0 


Map Response 


Mapltem 



o (16/48) 

0 (4) 

t — 2 (6) 

u ~ 0 (6) 


MR i ,2 

MR o 
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Map Reject 


MR 2 
MR i 
MR o 

<to responds with a map reject message if the page is reserved (i.e., kernel space) or already 
mapped to a different thread, or if memory is exhausted. 


nilpage (32 /64) 

0 (28/60) 

1000 

0 (16/48) 

0 (4) 

< - 2 (6) 

u = 0 (6) 
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7.7 Generic Booting [Protocol] 


Machine-specific boot procedures are described on pages 101 ff. 

After booting, L4 initializes itself. It generates the basic address space-servers ao, a\ and a root server which is 
intended to boot the higher-level system. 

ao, (Ji and the root server are user-level servers and not part of the pure kernel. The predefined ones can be replaced by 
modifying the following table in the L4 image before starting L4. An empty area specifies that the corresponding server 
should not be started. Note, that ao is a mandatory service. The kernel debugger kdebug is also not part of the kernel and 
can accordingly be replaced by modifying the table. 


MemoryDesc 


MemDescPtr 


+B0/+160 
+A0/+140 
+90/ +120 
+80/ +100 
+70/ +E0 
+60/ +C0 
+50/ +A0 
+40/ +80 
+30/ +60 
+20/ +40 
+ 10 / +20 
+0 


The addresses are offsets relative to the configuration page’s base address. The configuration page is located at a page 
boundary and can be found by searching for the magic “L4piK” starting at the load address. The IP and SP values 
however, are absolute addresses. The appropriate code must be loaded at these addresses before L4 is started. 



Bootlnfo 







Kdebug. configl 

Kdebug. configO 

Memorylnfo 


root server.high 

root server, low 

root server. IP 

root server. SP 

<ti .high 

(T X .low 

(Tl .IP 

0-1. SP 

<J0 -high 

(JQ .lOW 

0-0 .IP 

o- 0 .SP 

Kdebug.high 

Kdebug. low 

Kdebug. entry 

Kdebug.init 


API Version 



+C/+18 +8/ +10 +4/ +8 +0 


IP Physical address of a server’s initial instruction pointer (start). 


SP Physical address of a server’s initial stack pointer (stack bottom). 


Kdebug.init 


Physical address of kdebug ' s initialization routine. 
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Kdebug.entry 

Kdebug.low 

Kdebug.high 

Kdebug.config 

Bootlnfo 

Memorylnfo 

MemDescPtr 

n 

MemoryDesc 

high 

low 

v 

type 


Physical address of kdebug’s exception handler entry point. 


Physical address of first byte of kernel debugger. Must be page aligned. 


Physical address of last byte of kernel debugger. Must be the last byte in page. 


Configuration fields which can be freely interpreted by the kernel debugger. The specific seman- 
tics of these fields are provided with the specific kernel debuggers. 


Prior to kernel initialization a boot loader can write an arbitrary value into this field. Post- 
initialization code, e.g., a root server can later read the field. Its value is neither changed nor 
interpreted by the kernel. This is the generic method for passing system information across 
kernel initialization. 


MemDescPtr (i 6 / 32 ) 


n (16/32) 


Location of first memory descriptor (as an offset relative to the configuration page’s base ad- 
dress). Subsequent memory descriptors are located directly following the first one. For memory 
descriptors that specify overlapping memory regions, later descriptors take precedence over ear- 
lier ones. 

Initially equals the number of available memory descriptors in the configuration page. Before 
starting L4 this number must be initialized to the number of inserted memory descriptors. 


+4/ +8 
+0 

Memory descriptors should be initialized before starting L4. The kernel may after startup insert 
additional memory descriptors or modify existing ones (e.g., for reserved kernel memory). 


high/2 10 (22 / 54 ) 

~ (10) 

low/2 10 ( 22 / 54 ) 

I 

R 

f (4) 

type (4) 


Address of last byte in memory region. The ten least significant address bits are all hardwired 
to 1. 

Address of first byte in memory region. The ten least significant address bits are all hardwired 
to 0. 

Indicates whether memory descriptor refers to physical memory (v = 0) or virtual memory 

(v - 1 ). 

Identifies the type of the memory descriptor. 


Type 

Description 

0x0 

Undefined 

0x1 

Conventional memory 

0x2 

Reserved memory (i.e., reserved by kernel) 

0x3 

Dedicated memory (i.e., memory not available to user) 

0x4 

Shared memory (i.e., available to all users) 

OxE 

Defined by boot loader 

OxF 

Architecture dependent 


t 


Identifies the precise type for boot loader specific or architecture dependent memory descriptors. 
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type = 0 xE 

The type of the memory descriptor is dependent on the bootloader. The t field specifies the exact 
semantics. Refer to boot loader specification for more info. 

type = 0 xF 

The type of the memory descriptor is architecture dependent. The t field specifies the exact 
semantics. Refer to architecture specific part for more info (see page 115). 

type ^ OxE, type # OxF 

The type of the memory descriptor is solely defined by the type field. The content of the t field 
is undefined. 



Appendix A 

IA-32 Interface 
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VIRTUAL REGISTERS 


A.1 Virtual Registers [ia32] 


Thread Control Registers (TCRs) 

TCRs are implemented as part of the ia32-specific user-level thread control block (UTCB). The address of the current 
thread's UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active thread via THREAD- 
CONTROL is similar to deletion and re-creation. There is a fixed correlation between the UtcbLocation parameter when 
invoking ThreadControl and the UTCB address. The UTCB address of the current thread can be loaded through a 
machine instruction 

mov %gs:[0], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must 
not be accessed, even if they are physically accessible. ThreadWordO and ThreadWordl are free to be used by systems 
software (e.g., IDL compilers). The kernel associates no semantics with these words. 


< — UTCB address 

-16 

-20 

-24 

-28 

-32 

-36 

-40 

-44 

-48 

-52 

-56 

-60 


gs:[0] 

The TCR MyLocalhl is not part of the UTCB. On ia32 it is identical with the UTCB address and 
can be loaded from memory location gs:[0]. 
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Message Registers (MRs) 

Memory-mapped MRs are implemented as part of the ia32-specific user-level thread control block (UTCB). The address 
of the current thread’s UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active thread 
via ThreadControl is similar to deletion and re-creation. There is a fixed correlation between the UtcbLocation 
parameter when invoking ThreadControl and the UTCB address. The UTCB address of the current thread can be 
loaded through a machine instruction 

mov %gs:[ 0 ], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must not 
be accessed, even if they are physically accessible. 

MR o is always mapped to a general register. MR i and MR 2 are mapped to general registers when reading a received 
message; in all other cases, MR i and MR 2 are mapped to memory locations. MR 3. ..63 are always mapped to memory. 


MR 0 


ESI 


MR 1 (only for msg receive) 


EBX 


MR 2 (only for msg receive) 


EBP 


MR 1...63 [UTCB fields] 

+252 


+16 
+ 12 
+8 

< — UTCB address + 4 


MR 63 (32) 


MR 


4 (32) 


MR 3 (32) 


MR 2 (except for msg receive) ( 32 ) 


MR 1 (except for msg receive) ( 32 ) 


Buffer Registers (BRs) 

BRs are implemented as part of the ia32-specific user-level thread control block (UTCB). The address of the current 
thread's UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active thread via THREAD- 
CONTROL is similar to deletion and re-creation. There is a fixed correlation between the UtcbLocation parameter when 
invoking THREADCONTROL and the UTCB address. The UTCB address of the current thread can be loaded through a 
machine instruction 

mov %gs:[ 0 ], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must not 
be accessed, even if they are physically accessible. 
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BR o 32 [UTCB fields] 

< — UTCB address 


-64 

-68 


-196 



UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address. . . UTCB address + 3. The application can 
use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the memory contents 
within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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A.2 Systemcalls [ia32] 


The system-calls which are invoked by the call instruction take the target of the calls the from system-call link fields in 
the kernel interface page (see page 2). Each system-call link specifies an address relative to the kernel interface page’s 
base address. An application may use instructions other than call to invoke the system-calls, but must ensure that a valid 
return address resides on the stack. 


KERNELlNTERFACE [Slow Systemcall] 


EAX 

— Kernellnterface — > 

eax base address 

ECX 


ECX API Version 

EDX 


EDX API Flags 

- ESI 

lock: nop 

ESI Kernel ID 

EDI 


EDI = 

EBX 


EBX = 

EBP 


EBP = 

- ESP 


ESP = 

ExchangeRegisters 

[Systemcall] 


dest EAX 

— Exchange Registers — > 

eax result 

control ECX 


ECX control 

SP EDX 


EDX SP 

IP ESI 

call ExchangeRegisters 

ESI IP 

FLAGS EDI 


EDI FLAGS 

UserDefinedHandle ebx 


EBX UserDefinedHandle 

pager EBP 


EBP pager 

- ESP 


ESP = 

“FLAGS” refers to the user-modifiable ia32 processor flags that are held in the EFLAGS register. 

THREADCONTROL [Privileged Systemcall] 


dest eax 

— Thread Control — > 

eax result 

Pager ECX 


ECX ~ 

Scheduler EDX 


EDX ~ 

SpaceSpecifier ESI 

call ThreadControl 

ESI ~ 

UtcbLocation EDI 


EDI ~ 

EBX 


EBX ~ 

EBP 


EBP ~ 

- ESP 


ESP = 


SYSTEMCLOCK [Systemcall] 


EAX 

SystemClock — > 

EAX clock 0 . .. 31 

ECX 


ECX ~ 

EDX 


edx clock 32. . . 63 

- ESI 

call SystemClock 

ESI ~ 

EDI 


EDI ~ 

EBX 


EBX = 

EBP 


EBP = 

- ESP 


ESP = 
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THREADSWITCH [Systemcall] 


dest EAX 

ECX 

EDX 

ESI 

EDI 

EBX 

EBP 

- ESP 

— ThreadSwitch — > 

call ThreadSwitch 

EAX = 

ECX = 

EDX = 

ESI = 

EDI = 

EBX = 

EBP = 

ESP = 

Schedule [Systemcaii] 

dest eax 

— Schedule — > 

EAX result 

prio ECX 


ECX ~ 

time control edx 


EDX time control 

processor control ESI 

call Schedule 

ESI ~ 

preemption control EDI 


EDI ~ 

EBX 


EBX ~ 

EBP 


EBP ~ 

- ESP 


ESP = 

IPC [Systemcall] 

tO EAX 

— Ipc — > 

EAX from 

Timeouts ECX 


ECX ~ 

FromSpecifier EDX 


EDX ~ 

MR o ESI 

call Ipc 

ESI MR o 

UTCB EDI 


EDI = 

EBX 


EBX MR i 

EBP 


EBP MR 2 

ESP 


ESP = 

Ll PC [Systemcall] 

tO EAX 

— Lipc — * 

EAX from 

Timeouts ECX 


ECX ~ 

FromSpecifier EDX 


EDX ~ 

MR o ESI 

call Lipc 

ESI MR o 

UTCB EDI 


EDI = 

EBX 


EBX MR 1 

EBP 


EBP MR 2 

ESP 


ESP = 

UNMAP [Systemcall] 

control eax 

— Unmap — > 

EAX ~ 

ECX 


ECX ~ 

EDX 


EDX ~ 

MR o ESI 

call Unmap 

ESI MR o 

UTCB EDI 


EDI = 

EBX 


EBX ~ 

EBP 


EBP ~ 

- ESP 


ESP = 
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SPACECONTROL [Privileged Systemcall] 


SpaceSpecifier EAX 

— Space Control — > 

eax result 

control ECX 


ECX control 

KernellnteifacePageArea edx 


EDX ~ 

UtcbArea ESI 

call SpaceControl 

ESI ~ 

Redirector EDI 


EDI ~ 

EBX 


EBX ~ 

EBP 


EBP ~ 

- ESP 


ESP = 


PROCESSORCONTROL [Privileged Systemcall] 


ProcessorNo EAX 

— Processor Control — > 

EAX result 

InternalFrequency ECX 


ECX ~ 

ExternalFrequency EDX 


EDX ~ 

voltage ESI 

call ProcessorControl 

ESI ~ 

EDI 


EDI ~ 

EBX 


EBX ~ 

EBP 


EBP ~ 

- ESP 


ESP = 


MEMORYCONTROL [Privileged Systemcall] 


control 

EAX 

Memory Control — > 

eax result 

attributed 

ECX 


ECX ~ 

attributei 

EDX 


EDX ~ 

MR o 

ESI 

call MemoryControI 

ESI ~ 

UTCB 

EDI 


EDI ~ 

attribute2 

EBX 


EBX ~ 

attribute?, 

EBP 


EBP ~ 

- 

ESP 


ESP = 
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A.3 Kernel Features [ia32] 

The ia32 architecture supports the following kernel feature descriptors in the kernel interface page (see page 4). 

String Feature 


“smallspaces” Kernel has small address spaces enabled. 
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A.4 10-Ports [ia32] 


On ia32 processors, 10-ports are handled as fpages. 10 fpages can be mapped, granted, and unmapped like memory 
fpages. Their minimal granularity is 1. An IO-fpage of size 2 s has a 2 s -aligned base address p, i.e. p mod 2 s =0. An 
fpage with base port address p and size 2 s is denoted as described below. 


lOfpage (p, 2 s ') 


P (16/48) 

S’ (6) 

8 ~ 2 (6) 

Or wx 


IO-ports can only be mapped idempotently. i.e., physical port x is either mapped at 10 address x in the task’s IO address 
space, or it is not mapped at all. 


Generic Programming Interface 

#include <l4/space.h> 

Fpage IoFpage (Word BaseAddress, int FpageSize) 

Fpage IoFpageLog2 (Word BaseAddress, int LoglFpageSize < 64) 

Delivers an IO fpage with the specified location and size. 
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A.5 Space Control [ia32] 


The SpaceControl system call has an architecture dependent control parameter to specify various address space char- 
acteristics. For ia32, the control parameter has the following semantics. 


Input Parameter 


control 


0 ( 23 ) 


small (gj 


A value of 1 indicates the intention to change the small address space number for the specified 
address space. The small space number will remain unchanged if s = 0. 


small If s = 1, sets the small address space number for the specified address space. Small address 
space numbers from 1 to 255 are available. A value of 0 indicates a regular large address space. 
An assigned small space number is effective on all CPUs in an SMP system. 

The position ( pos ) of the least significant bit of small indicates the size of the small space by the 
following formula: size = 2 pos * 4 MB. After removing the least significant bit, the remaining 
bits of small indicate the location of the space within a 512 MB region using the following 
formula: location = small * 2 MB. Setting the small space number fails if the specified region 
overlaps with an already existing one. 

The small field is ignored if s = 0. or if the kernel does not support small spaces (see Kernel 
Features, page 94). 


Output Parameter 


control 


e 


0 


( 23 ) 


small 


(8) 


e Indicates if the change of small space number was effective (e = 1). Undefined if s = 0 in the 

input parameter. 

small The old value for the small space number. A value of 0 is possible even if the space has pre- 
viously been put into a small address space. An implicit change to small space number 0 can 
happen if a thread within the space accesses memory beyond the specified small space size. 


Generic Programming Interface 


#include <l4/space.h> 

Word LargeSpace 


Word SmallSpace ( Word location, size ) 

Delivers a small space number with the specified location and size (both in MB). It is assumed 
that size = 2 P * 4 for some value p < 8. 
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A.6 Cacheability Hints [ia32] 

String items can specify cacheability hints to the kernel (see page 54). For ia32, the cacheability hints have the following 
semantics. 

hh — oq Use the processor’s default cacheability strategy. Typically, cache lines are allocated for data 
read and written (assuming that the processor’s default strategy is write-back and write-allocate). 

hh = 01 Allocate cache lines in the entire cache hierarchy for data read or written. 

hh = 10 Do not allocate new cache lines (entire cache hierarchy) for data read or written. 

hh = 11 Allocate only new LI cache line for data read or written. Do not allocate cache lines in lower 
cache hierarchies. 


Convenience Programming Interface 

#include <l4/ipc.h> 

CacheAllocationHint UseDefaultCacheLineAllocation 
CacheAllocationHint AllocateNewCacheLines 
CacheAllocationHint DoNotAllocateNewCacheLines 
CacheAllocationHint AllocateOnlyNewLl CacheLines 
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A.7 Memory Attributes [ia32] 

The ia32 architecture in general supports the following memory attributes values. 


attribute 

value 

Default 

0 

Uncacheable 

1 

Write Combining 

2 

Write Through 

5 

Write Protected 

6 

Write Back 

7 


Note that some attributes are only supported on certain processors. See the “IA-32 Intel Architecture Software Devel- 
oper’s Manual, Volume 3: System Programming Guide” for the semantics of the memory attributes and which processors 
they are supported on. 


Generic Programming Interface 

#include <l4/misc.h> 

Word DefaultMemory 
Word UncacheableMemory 
Word WriteCombiningMemory 
Word WriteThroughMemory 
Word WriteProtectedMemory 
Word WriteBackMemory 
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A .8 Exception Message Format 1*32] 


To Exception Handler 


EAX ( 32 ) 

ECX {32) 

EDX (32) 

EBX (32) 

ESP (32) 

EBP (32) 

ESI (32) 

EDI (32) 

ErrorCode ( 32 ) 

ExceptionNo ( 32 ) 

EFLAGS ( 32 ) 

EIP (32) 

— 4/ — 5 (12/44) 0 (4) 0(4) t = 0 (g) U = 12 (6) 


MR 12 
MR n 
MR io 
MR 9 
MR 8 
MR- 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 


#PF (page fault), #MC (machine check exception), and some #GP (general protection), #SS (stack segment fault), and 
#NM (no math coprocessor) exceptions are handled by the kernel and therefore do not generate exception messages. 

Note that executing an INT n instructions in 32-bit mode will always raise a #GP (general protection). The exception 
handler may interpret the error code (8 n + 2, see processor manual) and emulate the INT n accordingly. 
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A.9 Processor Mirroring [ia32] 


Segments 

L4 uses a flat (unsegmented) memory model. There are only three segments available: user^space, a read/write segment, 
user_space_exec, an executable segment, and utcb_address, a read-only segment. Both user_space and userjpace.exec 
cover (at least) the complete user-level address space. \Jtcb.address covers only enough memory to hold the UTCB 
address. 

The values of segment selectors are undefined. When a thread is created, its segment registers SS, DS, ES and FS 
are initialized with user_space , GS with utcb .address, and CS with user .space _exec. Whenever the kernel detects a 
general protection exception and the segment registers are not loaded properly, it reloads them with the above mentioned 
selectors. From the user's point of view, the segment registers cannot be modified. 

However, the binary representation of user^space and user jpace. exec may change at any point during program exe- 
cution. Never rely on any particular value. 

Furthermore, the LSL (load segment limit) machine instruction may deliver wrong segment limits, even floating ones. 
The result of this instruction is always undefined. 


Debug Registers 

User-level debug registers exist per thread. DRO. ..3, DR6 and DR7 can be accessed by the machine instructions 
mov n,DRx and mov DRx,r. However, only task-local breakpoints can be activated, i.e., bits GO. . . 3 in DR7 cannot be 
set. Breakpoints operate per thread. Breakpoints are signaled as #DB exception (INT 1). 

Note that user-level breakpoints are suspended when kernel breakpoints are set by the kernel debugger. 


Model-Specific Registers 

All privileged threads in the system have read and write access to all the Model-Specific Registers (MSRs) of the CPU. 
Modification of some MSRs may lead to undefined system behavior. Any access to an MSR by an unprivileged thread 
will raise an exception. 
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A.10 Booting [ia32] 


PC-compatible Machines 

L4 can be loaded at any 16-byte-aligned location beyond 0x1000 in physical memory. It can be started in real mode 
or in 32-bit protected mode at address 0x100 or 0x1000 relative to its load address. The protected-mode conditions are 
compliant to the Multiboot Standard Version 0.6. 


Start Preconditions 


Real Mode 

32-bit Protected Mode 

load base (L) 

L > 0x1000, 16-byte aligned 

L> 0x1000 

load offset (X) 

X = 0x100 or X = 0x1000 

X = 0x100 or X = 0x1000 

Interrupts 

disabled 

disabled 

Gate A20 

~ 

open 

EFLAGS 

1=0 

1=0, VM=0 

CR0 

PE=0 

PE=1, PG=0 

(E)IP 

X 

L + X 

CS 

L/ 16 

0. 4GB, 32-bit exec 

SS.DS.ES 


0, 4GB, read/write 

EAX 


0x2BADB0O2 

EBX 


*P 

(P + 0) 


~ OR 1 

(P + 4> 

n/a 

below 640 K mem in K 

(P + 8) 


beyond 1M mem in K 

all remaining registers & flags 



(general, floating point, 



ESP, xDT, TR, CRx, DRx) 




L4 relocates itself to 0x1000, enters protected mode if started in real mode, enables paging and initializes itself. 
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Appendix B 

IA-64 Interface 
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B.1 Virtual Registers [ia64] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the ia64-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB will not change over the lifetime of the thread. (In fact, 
the ia64 UTCB address is identical to the thread’s local ID.) Register ar.k6 always contains the UTCB address of the 
current thread. UTCBs of other threads must not be accessed, even if they are physically accessible. ThreadWordO and 
ThreadWordl are free to be used by systems software (e.g., IDL compilers). The kernel associates no semantics with 
these words. 


( 48 ) 


ThreadWord 1 (g 4 ) 


ThreadWordO (g 4 ) 


ErrorCode ( 64 j 


VirtualSender/ActualSender ( 64 j 


IntendedReceiver (g 4 ) 


XferTimeouts (g 4 ) 


cop flags (8 ) 


ExceptionHandler 


preempt flags (g) 


Pager (64) 


UserDefinedHandle (g 4 ) 


ProcessorNo jg 4 ) 


+352 

+344 

+72 
+64 
+56 
+48 
+40 
+32 
+24 
+ 16 

< — UTCB address + 8 


MyLocalld = UTCB address (g 4 ) 


MyGloballd ( 64 ) 


ar.k6 

ar.k5 


Message Registers (MRs) 

Memory-mapped MRs are implemented as part of the ia64-specific user-level thread control block (UTCB). The address 
of the current thread’s UTCB will not change over the lifetime of the thread. (In fact, the ia64 UTCB address is identical 
to the thread's local ID.) Register ar.k6 always contains the UTCB address of the current thread. UTCBs of other threads 
must not be accessed, even if they are physically accessible. 

MR ,,.. .7 are mapped to the eight first output registers on the register stack. The exact location of the first eight message 
registers therefore depends on the configuration of the current frame marker (CFM). MR g .,.63 are mapped to memory. It 
is valid to configure less than eight output registers in the current register frame if a message to be transferred spans less 
than eight message registers. The number of message registers must not exceed the number of output registers, however. 
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out7 

out6 

out5 

out4 

out3 

out2 

outl 

outO 


+888 

+456 

< — UTCB address + 448 


Buffer Registers (BRs) 

BRs are implemented as part of the ia64-specific user-level thread control block (UTCB). The address of the current 
thread's UTCB will not change over the lifetime of the thread. (In fact, the ia64 UTCB address is identical to the thread’s 
local ID.) Register ar.k6 always contains the UTCB address of the current thread. UTCBs of other threads must not be 
accessed, even if they are physically accessible. 


BR o 32 [UTCB fields] 

+336 


+88 

< — UTCB address + 80 


BR 32 


BR 1 


BR 0 


UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 384. . . UTCB address + 447. The 
application can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the 
memory contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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B.2 PAL and SAL Access ua64] 


The microkernel provides special system-calls for accessing Processor Abstraction Level (PAL) and System Abstraction 
Layer (SAL) procedures. The location of the additional system-call links in the kernel interface page are as follows: 


Location 

Kernel Interface Page + 0x220 
Kernel Interface Page + 0x228 


System-call 

PAL.Call 

SAL.Call 


Generic Programming Interface 

System-Call Function: 

#include <l4/arch.h> 

Word PAL Call ( Word idx, al, a2, a3, Word& rl, r2, r3 ) 

Invoke the PAL procedure specified by idx. al. . ,a3 are the arguments to the PAL procedure. 
rl... r3 are the return values. The system-call returns the status of the procedure invocation. See 
the “Intel Itanium Architecture Software Developer's Manual. Volume 2: System Architecture” 
for the possible values of idx, and the contents of arguments and return values. 

As of now, no invocation of PAL procedures is allowed by any user-level thread. 

Word SAL-Call ( Word idx, al, a2, a3, a4, a5, a6, Word& rl, r2, r3) 

Invoke the SAL procedure specified by idx. al. ,.a6 are the arguments to the SAL procedure. 
rl... r3 are the return values. The system-call returns the status of the procedure invocation. See 
the “Itanium Processor Family System Abstraction Layer Specification” for possible values of 
idx, and the contents of arguments and return values. 

As of now, only the PCI_CONFIG_READ and PCI_CONFIG_WRITE procedure calls can be 
invoked from a user-level thread. 


Convenience Programming Interface 

Derived Functions: 

#include <l4/arch.h> 

Word SAL_PCI JJonfigRead ( Word address, size, Word& value ) 

Read from the PCI configuration space at address with the indicated word size (1, 2 or 4 bytes). 
The read value is returned in value. Return the status of the operation (0 if success). 

The operation will only succeed if the address in the PCI configuration space is mapped readable 
(see page 112) 

Word SAL_PCIJConfigWrite (Word address, size, value ) 

Write value to the PCI configuration space at address with the indicated word size (1, 2 or 4 
bytes). Return the status of the operation (0 if success). 

The operation will only succeed if the address in the PCI configuration space is mapped writeable 
(see page 112). 



SYSTEMCALLS 


107 


B.3 Systemcalls [ia64] 


The system-calls which are invoked by the br.call instruction take the target of the calls the front system-call link fields in 
the kernel interface page (see page 2). Each system-call link value, v, specifies either an absolute address (if v > 1MB) 
or an address relative to the kernel interface page’s base address (if v < 1MB). An application may use instructions 
other than br.call to invoke the system-calls, but must ensure that a valid return address resides in the bO register. For the 
IPC and LlPC system-calls the application must additionally ensure that message registers are mapped into input registers 
after invoking the system-call (i.e., the output registers if one were to use a br.call instruction). 


The system-call definitions below only specify the contents of the general registers. Except for the KERNELlNTERFACE, 
Ipc and LlPC system-calls, the contents of the remaining user accessible registers closely resembles the IA-64 software 
calling conventions. More precisely, the register contents of these registers are ignored upon system-call entry, and the 
contents after system-call exit are defined as follows: 


Floating-point Registers: 


Application Registers: 


fO. . . f 1 

fixed 

ar.fpsr 

special (see below) 

f2...f5 

preserved 

ar.rnat 

preserved 

f6. . . f 15 

scratch 

ar.unat 

preserved 

f 1 6. . . f 127 

preserved 

ar.pfs 

scratch 



ar.bsp 

preserved 

ite Registers 


ar.bspstore 

preserved 

P 0 

fixed 

ar.rsc 

special (see below) 

pl...p5 

preserved 

ar.lc 

preserved 

p6. . .pl5 

scratch 

ar.ec 

preserved 

pl6. . .p63 

preserved 

ar.ccv 

scratch 



ar.itc 

scratch 

Registers: 


ar.kO. . . k4 

scratch 

bO 

system-call return address 

ar.k5 

MyGloballd 

bl...b5 

preserved 

ar.k6 

MyLocalld 

b6. . . b7 

scratch 

ar.k7 

scratch 


The ar.fpsr and ar.rsc registers are special. The second and third status fields of ar.fpsr, and the loadrs field of ar.rsc have 
scratch semantics. The remaining fields have preserved semantics. 


KERNELlNTERFACE [Slow Systemcall] 


rl... r7 
r8 

— r9 
rlO 
rll 

rl2. . . r31 

— inO. . . in95 

— locO. . . loc95 

— outO. . . out95 


— Kernellnterface — > 


{ .mix 

( qp ) break.m Oxlface 

(qp) movl rO = 0x0 ;; 

} 


rl. . . r7 

— 

r8 

base address 

r9 

API Version 

rlO 

API Flags 

rll 

Kernel ID 

rll. . . r31 

= 

inO. . . in95 

= 

locO. . . loc95 

= 

outO. . . out95 

= 


All other registers remain unchanged. A qualifying predicate, qp, can be used to conditionally execute the KernelIn- 
TERFACE system-call. 
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EXCHANGEREGISTERS [Systemcall] 


- 

rl 

— ExchangeRegisters — ► 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8. . . rll 

br.call bO = ExchangeRegisters 

r8. . . rll 

~ 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

dest 

rl4 


rl4 

result 

contol 

rl5 


rl5 

control 

SP 

rl6 


rl6 

SP 

IP 

rl7 


rl7 

IP 

FLAGS 

rl8 


rl8 

FLAGS 

UserDefinedHandle 

rl9 


rl9 

UserDefinedHandle 

pager 

r20 


r20 

pager 

- 

r21. . . r31 


r21. . . r31 



outO. . . out95 


outO. . . out95 


ThreadControl 

[Privileged Systemcall] 



— 

rl 

— ThreadControl — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = ThreadControl 

r8 

result 

- 

r9. . . rll 


r9. . . rll 

~ 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

dest 

rl4 


rl4 

~ 

SpaceSpecifier 

rl5 


rl5 

~ 

Scheduler 

rl6 


rl6 


Pager 

rl7 


rl7 

~ 

UtcbLocation 

rl8 


rl8 


- 

rl9. . . r31 


rl9. . . r31 

~ 


outO. . . out95 


outO. . . out95 


SYSTEMCLOCK [Systemcall] 



- 

rl 

— SystemClock — ► 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = SystemClock 

r8 

clock 

- 

r9. . . rll 


r9. . . rll 


- 

rl2. . . rl3 


rl2. . . rl3 

= 

- 

rl4. . . r31 


rl4. . . r31 

~ 


outO. . . out95 


outO. . . out95 


THREADSWITCH [Systemcall] 



_ 

rl 

— ThreadSwitch — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8. . . rll 

br.call bO = ThreadSwitch 

r8. . . rll 

~ 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

dest 

rl4 


rl4 

~ 

- 

rl5. . . r31 


rl5. . . r31 



outO. . . out95 


outO. . . out95 
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Schedule [Systemcaii] 


- 

rl 

— Schedule — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = Schedule 

r8 

result 

- 

r9 


r9 

time control 

- 

rlO. .. rll 


rlO. ..rll 


- 

rl2. . . rl3 


rl2. . . rl3 

= 

dest 

rl4 


rl4 


time control 

rl5 


rl5 


processor control 

rl6 


rl6 


prio 

rl7 


rl7 


preemption control 

rl8 


rl8 


- 

rl9. . . r31 


rl9. . . r31 


- 

outO. . . out95 


outO. . . out95 



I PC [Systemcaii] 


- 

rl 

— Ipc — > 

rl 

= 

- 

r2. . . r8 


r2. . . r8 


- 

r9 


r9 

from 

- 

rlO. ..rll 

br.call bO = Ipc 

r 10... rll 

~ 

- 

rl2 


rl2 

= 

- 

rl3 


rl3 

~ 

to 

rl4 


rl4 

~ 

FromSpecifier 

rl5 


rl5 

~ 

Timeouts 

rl6 


rl6 

~ 

- 

rl7... r31 


rl7...r31 

~ 

MR o 

outO 


outO 

MR Q 

MR i 

outl 


outl 

MR i 

MR 2 

out2 


out2 

MR 2 

MR 3 

out3 


out3 

MR 3 

MR 4 

out4 


out4 

MR 4 

MR 5 

out5 


out5 

MR 5 

MR 6 

out6 


out6 

MR 6 

MR 7 

out7 


out7 

MR 7 

- 

out8. . . out95 


out8. . . out95 

~ 


All remaining registers (including application registers) will have scratch semantics over the IPC system-call. Upon entry 
to the IPC system-call, the register stack backing store must be able to contain the dirty partition of the register stack. 


LlPC [Systemcaii] 


- 

rl 

— Lipc — > 

rl 

= 

- 

r2. . . r8 


r2. . . r8 


- 

r9 


r9 

from 

- 

r 10... rll 

br.call bO = Lipc 

r 10... rll 

~ 

- 

rl2 


rl2 

= 

- 

rl3 


rl3 

~ 

to 

rl4 


rl4 

~ 

FromSpecifier 

rl5 


rl5 

~ 

Timeouts 

rl6 


rl6 

~ 

- 

rl7...r31 


rl7...r31 

~ 

MR a 

outO 


outO 

MRo 

MR i 

outl 


outl 

MR i 

MR 2 

out2 


out2 

MR 2 

MR 3 

out3 


out3 

MR 3 

MR 4 

out4 


out4 

MR 4 

MR 5 

out5 


out5 

MR 5 

MR 6 

out6 


out6 

MR 6 

MR 7 

out7 


out7 

MR 7 

- 

out8. . . out95 


out8. . . out95 

~ 
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All remaining registers (including application registers) will have scratch semantics over the LlPC system-call. Upon 
entry to the LlPC system-call, the register stack backing store must be able to contain the dirty partition of the register 
stack. 


UNMAP [Systemcall] 





- 

rl 

— Unmap — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8. . . rll 

br.call bO = Unmap 

r8. . . rll 

~ 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

control 

rl4 


rl4 

~ 

- 

rl5. . . r31 


rl5. . . r31 


MR o 

outO 


outO 

MR o 

MR 1 

outl 


outl 

MR i 

MR 2 

out2 


out 2 

MR 2 

MR 3 

out3 


out3 

MR 3 

MR 4 

out4 


out4 

MR 4 

MR 5 

out5 


out 5 

MR 5 

MR 6 

out6 


out6 

MR 6 

MR 7 

out7 


out7 

MR 7 


out8. . . out95 


out8. . . out95 


SPACECONTROL [Privileged Systemcall] 



— 

rl 

— Space Control — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = SpaceControl 

r8 

result 

- 

r9 


r9 

control 

- 

r 10... rll 


r 10... rll 


- 

rl2. . . rl3 


rl2. . . rl3 

= 

SpaceSpecifier 

rl4 


rl4 

~ 

control 

rl5 


rl5 


KernellnterfacePcigeArci 

rl6 


rl6 

~ 

UtcbArea 

rl7 


rl7 


Redirector 

rl8 


rl8 

~ 

- 

rl9... r31 


rl9. . . r31 



outO. . . out95 


outO. . . out95 


PROCESSORCONTROL [Privileged Systemcall] 



_ 

rl 

— Processor Control — > 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = Processor-Control 

r8 

result 

- 

r9. . . rll 


r9. . . rll 

~ 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

ProcessorNo 

rl4 


rl4 

~ 

Internal Frequency 

rl5 


rl5 

~ 

ExtemalFreqyency 

rl6 


rl6 


voltage 

rl7 


rl7 

~ 

~ 

rl8. . . r31 


rl8. . . r31 



outO. . . out95 


outO. . . out95 
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MemoryControl 

[Privileged Systemcall] 



- 

rl 

— Memory Control — > 

rl 

= 

- 

r2. . . r3 


r2. . . 

r3 ~ 

- 

r4. . . r7 


r4. . . 

r7 = 

- 

r8 

br.call bO = MemoryControl 

r8 

result 

- 

r9. . . rll 


r9... 

rll ~ 

- 

rl2. . . rl3 


rl2. . 

. rl3 = 

control 

rl4 


rl4 


attributeo 

rl5 


rl5 


attributes 

rl6 


rl6 


attribute 2 

rl7 


rl7 


attributes 

rl8 


rl8 


- 

rl9. . . r31 


rl9. . 

.r31 ~ 

MR 0 

outO 


outO 


MR-l 

out 1 


outl 


MR 2 

out2 


out2 


MR 3 

out3 


out3 


MR 4 

out4 


out4 


MR 5 

out5 


out5 


MR 6 

out6 


out6 


MR 7 

out7 


out7 


- 

out8. . . out95 


out8. 

. . out95 ~ 


PAI CALL [Architecture Specific Systemcall] 


- 

rl 

- PAL Call -*• 

rl 

= 

- 

r2. . . r3 


r2. . . r3 


- 

r4. . . r7 


r4. . . r7 

= 

- 

r8 

br.call bO = PAL_Call 

r8 

status 

- 

r9 


r9 

retl 

- 

rlO 


rlO 

ret2 

- 

rll 


rll 

ret3 

- 

rl2. . . rl3 


rl2. . . rl3 

= 

- 

rl4. . . r27 


rl4. . . r27 


idx 

r28 


r28 


argl 

r29 


r29 


arg2 

r30 


r30 


arg3 

r31 


r31 


- 

outO. . . out95 


outO. . . out95 



SAI CALL [Architecture Specific Systemcall] 


rl 

r2. . . r3 
r4. . . r7 
r8 


- SAL Call 


br.call bO = SAL_CaIl 


- 

r9 

- 

rlO 

- 

rll 

- 

rl2. . . rl3 

- 

rl4. . . r31 

idx 

outO 

argl 

outl 

arg2 

out2 

arg3 

out3 

arg4 

out4 

arg5 

out5 

arg6 

out6 

- 

out7. . . out95 


rl 

— 

r2. . . r3 


r4. . . r7 

= 

r8 

status 

r9 

retl 

rlO 

ret2 

rll 

ret3 

rl2. . . rl3 

= 

rl4. . . r31 


outO 


outl 


out2 


out3 


out4 


out5 


out6 


out7. . . out95 
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BA PCI Configuration Space [ia 64 ] 


On ia64 processors, the PCI configuration space is handled as fpages. PCI Config fpages can be mapped, granted, and 
unmapped like memory fpages. Their minimal granularity is 256 (i.e., one single device function). A PCI config fpage 
of size 2 s has a 2 s -aligned base address p, i.e. p mod 2 s =0. An fpage with base PCI configuration address p and size 
2 s is denoted as described below. 


PCI config fpage (p, 2 s ') 


P (48) 

s ’ (6) 

S — 2 (6) 

0 rwx 


The execute bit of the PCI config fpage is ignored. 


Generic Programming Interface 

#include <l4/space.h> 

Fpage PCIConfigFpage ( Word BaseAddress, int FpageSize > 256) 

Fpage PCIConfigFpageLog2 {Word BaseAddress, int LoglFpageSize < 64) 

Delivers a PCI config fpage with the specified location and size. 
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B.5 Cacheability Hints [ia64] 

String items can specify cacheability hints to the kernel (see page 54). For ia64, the cacheability hints have the following 
semantics. 

hh — oq Use the default cacheability strategy. Temporal locality is assumed for all cache levels. That is, 
cache lines are allocated on all levels for both data read and written. 

— 01 No temporal locality is assumed for the first level cache. Temporal locality is assumed for all 

lower cache levels. That is, cache lines are allocated on all cache levels below LI for both data 
read and written. 

— io No temporal locality is assumed for the first and second level caches. Temporal locality is 

assumed for all lower cache levels. That is, cache lines are allocated on all cache levels below 
L2 for both data read and written. 

— ii No temporal locality is assumed on any cache level. That is, cache lines are not allocated on any 

cache level. 

Note that support for cacheability hints is processor dependent. Refer to the processor specification to see what type of 
locality hints the processor supports for load and store instructions. 


Convenience Programming Interface 

#include <l4/ipc.h> 

CacheAllocationHint UseDefaultCacheLineAllocation 
CacheAllocationHint CacheNon TemporalLl 
CacheAllocationHint CacheNon TemporalL2 
CacheAllocationHint CacheNon TemporalAllLevels 
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B.6 Memory Attributes [ia64] 

The ia64 architecture in general supports the following memory attributes values. 


attribute 

value 

Default 

0 

Write Back 

1 

Write Coalescing 

7 

Uncacheable 

5 

Uncacheable Exported 

6 

NaT Page 

8 


Note that some attributes are only supported on certain processors. See the “Intel Itanium Architecture Software Devel- 
oper's Manual, Volume 2: System Architecture” for the semantics of the memory attributes. 


Generic Programming Interface 

#include <l4/misc.h> 

Word DefaultMemory 
Word WriteBackMemory 
Word WriteCoalescingMemory 
Word UncacheableMemory 
Word UncacheableExportedMemory 
Word NaTPageMemory 
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B.7 Memory Descriptors ua64] 

The following memory descriptors (see page 5) are specific to the ia64 architecture. 


t 

type 

Description 

Oxl 

OxF 

ACPI Memory 


Generic Programming Interface 


#include <l4/kip.h> 

Word ACPIMemoryType 
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B.8 Exception Message Format [ia64] 

To be defined. 



Appendix C 

PowerPC Interface 
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C.1 Virtual Registers [powerpc] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the PowerPC-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB is identical to the thread’s local ID, and is thus immutable. The 
UTCB address is provided in the general purpose register R2 at application start. The R2 register must contain the UTCB 
address for every system call invocation. UTCB objects of the current thread can be accessed as any other memory object. 
UTCBs of other threads must not be accessed, even if they are physically accessible. ThreadWordO and ThreadWordl 
are free to be used by systems software (e.g., IDL compilers). The kernel associates no semantics with these words. 


(32) 


< — UTCB address 


ThreadWordO ( 32 ) 

ThreadWord 1 ( 32 ) 

VirtualSender/ActualSender ( 32 ) 

IntendedReceiver ( 32 ) 

XferTimeouts ( 32 ) 

ErrorCode ( 32 ) 

~ (16) co P flags (8) preempt flags (8) 

ExceptionHandler ( 32 ) 

Pager (32) 

UserDefinedHandle ( 32 ) 

ProcessorNo ( 32 ) 

MyGloballd ( 32 ) 


-16 

-20 

-24 

-28 

-32 

-36 

-40 

-44 

-48 

-52 

-56 

-60 


MyLocalld = UTCB address ( 32 ) 


R2 


The TCR MyLocalld is not part of the UTCB. On PowerPC it is identical with the UTCB address 
and can be loaded from register R2. 


Message Registers (MRs) 

Message registers MRo through MR 9 map to the processor’s general purpose register file. The remaining message 
registers map to memory locations in the UTCB. MR 10 starts at byte offset 40 in the UTCB, and successive message 
registers follow in memory. 
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RO 

RIO 

R9 

R8 

R7 

R6 

R5 

R4 

R3 

R14 

+252 

+44 

< — UTCB address + 40 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BR« is at byte offset -64 in the UTCB. BR i at byte offset 
-68. etc. 


BR o 32 [UTCB fields] 

< — UTCB address 


-64 

-68 


-196 


( 32 ) 



UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address. . . UTCB address + 39. The application 
can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the memory contents 
within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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C.2 Systemcalls [powerpc] 


The PowerPC system calls are invoked by changing the location of the instruction pointer to the location of the system 
call address, with the return address in the link-return (LR) register. The invocation may take place via any mechanism 
which changes the instruction pointer location. The precise locations of the system calls are stored in the kernel interface 
page (see page 2). 

The locations of the system calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the kernel interface page. 

The registers defined to survive across system-call invocations (unless otherwise noted) are: Rl, R2, R30, R31, and 
the floating point registers. All other registers contain return values, are undefined, or may be preserved according to 
processor specific rules. 

The R2 register must contain the UTCB pointer when invoking all system calls. 

PowerPC uses one alternative system call invocation mechanism, for the KERNELlNTERFACE system call. This system 
call is invoked via the ’tibia’ instruction, and most registers are preserved across the function call. 


KERNELlNTERFACE [Slow Systemcall] 


UTCB R2 

— Kernellnterface — > 

R2 = 

- R3 


R3 KIP base address 

- R4 


R4 API Version 

R5 

tibia 

R5 API Flags 

- R6 


R6 Kernel ID 

R7 


R7 = 

- R8 


R8 = 

- R9 


R9 = 

- RIO 


RIO = 


For this system-call, all registers other than the output registers are preserved. The tibia instruction encoding is 
0x7c0002e4. 


EXCHANGEREGISTERS [Systemcall] 


UTCB 

R2 

— Exchange Registers — > 

R2 

= 

dest 

R3 


R3 

result 

control 

R4 


R4 

control 

SP 

R5 

call ExchangeRegisters 

R5 

SP 

IP 

R6 


R6 

IP 

FLAGS 

R7 


R7 

FLAGS 

UserDefinedHandle 

R8 


R8 

UserDefinedHandle 

pager 

R9 


R9 

pager 

- 

RIO 


RIO 



“FLAGS" refers to the user-modifiable PowerPC processor flags that are held in the MSR register. See the PowerPC 
Processor Mirroring section (page 127). 
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THREADCONTROL [Privileged Systemcall] 


UTCB R2 
dest R3 
SpaceSpecifier R4 
Scheduler R5 
Pager R6 
UtcbLocation R7 

- R8 

- R9 

- RIO 

— Thread Control — > 

call ThreadControl 

R2 = 

R3 result 

R4 ~ 

R5 rsj 

R6 ~ 

R7 ~ 

R8 ~ 

R9 ~ 

RIO ~ 

SYSTEMCLOCK [Systemcall] 


UTCB R2 

— SystemClock — > 

R2 = 

- R3 


R3 clock 32 . . . 63 

- R4 


R4 clock 0. ..31 

R5 

call SystemClock 

R5 ~ 

- R6 


R6 ~ 

R7 


R7 ~ 

- R8 


R8 ~ 

- R9 


R9 ~ 

- RIO 


RIO ~ 

THREADSWITCH [Systemcall] 


UTCB R2 

— ThreadSwitch — > 

R2 = 

dest R3 


R3 ~ 

- R4 


R4 ~ 

R5 

call ThreadSwitch 

R5 ~ 

- R6 


R6 ~ 

R7 


R7 ~ 

- R8 


R8 ~ 

- R9 


R9 ~ 

- RIO 


RIO ~ 

Schedule [Systemcall] 



UTCB R2 

— Schedule — > 

R2 = 

dest R3 


R3 result 

time control R4 


R4 time control 

processor control R5 

call Schedule 

R5 ~ 

prio R6 


R6 ~ 

preemption control R7 


R7 ~ 

- R8 


R8 ~ 

- R9 


R9 ~ 

- RIO 


RIO ~ 
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I PC [Systemcall] 


MR g 

RO 

— Ipc — > 

RO 

MRq 

- 

R1 


R1 

= 

UTCB 

R2 


R2 

= 

MR i 

R3 

call Ipc 

R3 

MR i 

MR 2 

R4 


R4 

MR 2 

MR 3 

R5 


R5 

MR 3 

MR 4, 

R 6 


R 6 

MR 4 

MR 5 

R7 


R7 

MR s 

MR 6 

R 8 


R 8 

MRq 

MR 7 

R9 


R9 

MR 7 

MR 8 

RIO 


RIO 

MR 8 

- 

Rll 


Rll 

~ 

- 

R12 


R12 

~ 

- 

R13 


R13 

~ 

MRq 

R14 


R14 

MRq 

to 

R15 


R15 


FromSpecifier 

R16 


R16 

from 

Timeouts 

R17 


R17 


LlPC [Systemcall] 




MR 9 

RO 

— Lipc — > 

RO 

MRq 

- 

R1 


R1 

= 

UTCB 

R2 


R2 

= 

MR 4 

R3 

call Lipc 

R3 

MR 4 

MR 2 

R4 


R4 

MR 2 

MR 3 

R5 


R5 

MR 3 

MR 4, 

R6 


R6 

MR 4 

MR 5 

R7 


R7 

MRq 

MR 6 

R8 


R8 

MRq 

MR 7 

R9 


R9 

MR 7 

MR 8 

RIO 


RIO 

MR 8 

- 

Rll 


Rll 

~ 

- 

R12 


R12 

~ 

- 

R13 


R13 

~ 

MRq 

R14 


R14 

MRq 

to 

R15 


R15 

~ 

FromSpecifier 

R16 


R16 

from 

Timeouts 

R17 


R17 


UNMAP [Systemcall] 




MR 9 

RO 

— Unmap — > 

RO 

MRq 

- 

R1 


R1 

= 

UTCB 

R2 


R2 

= 

MR 1 

R3 

call Unmap 

R3 

MR 4 

MR 2 

R4 


R4 

MR 2 

MR 3 

R5 


R5 

MR 3 

MR 4 

R6 


R6 

MR 4 

MR 5 

R7 


R7 

MRq 

MRq 

R8 


R8 

MRq 

MR 7 

R9 


R9 

MR 7 

MR 8 

RIO 


RIO 

MR 8 

- 

Rll 


Rll 

~ 

- 

R12 


R12 

~ 

- 

R13 


R13 

~ 

MRq 

R14 


R14 

MRq 

control 

R15 


R15 
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SPACECONTROL [Privileged Systemcall] 


men R2 

— Space Control — > 

R2 = 

SpaceSpecifier R3 


R3 result 

control R4 


R4 control 

KernellnterfacePageArea R5 

call SpaceControl 

R5 ~ 

UtcbArea R6 


R6 ~ 

Redirector R7 


R7 ~ 

- R8 


R8 ~ 

- R9 


R9 ~ 

- RIO 


RIO ~ 


PROCESSORCONTROL [Privileged Systemcall] 


UTCB 

R2 

— Processor Control — > 

R2 = 

processor no 

R3 


R3 result 

InternalFreq 

R4 


R4 ~ 

ExtemalFreq 

R5 

call Processor-Control 

R5 ~ 

voltage 

R6 


R6 ~ 

- 

R7 


R7 ~ 

- 

R8 


R8 ~ 

- 

R9 


R9 ~ 

- 

RIO 


RIO ~ 


MemoryControl 

[Privileged Systemcall] 


MR 9 

RO 

— Memory Control — > 

RO ~ 

- 

R1 


R1 = 

UTCB 

R2 


R2 = 

MR 1 

R3 

call MemoryControl 

R3 result 

MR n 

R4 


R4 ~ 

MR 3 

R5 


R5 ~ 

MR 4 

R6 


R6 ~ 

MR 5 

R7 


7?7 ~ 

MR 6 

R8 


7?<$ ~ 

MR 7 

R9 


R9 rsj 

MR s 

RIO 


RIO ~ 

- 

Rll 


Rll ~ 

- 

R12 


7?72 ~ 

- 

R13 


7?73 ~ 

MRq 

R14 


7?74 ~ 

control 

R15 


7?75 ~ 

attributed 

R16 


R16 ~ 

attributei 

R17 


R17 ~ 

attribute 2 

R18 


7?7S ~ 

attributez 

R19 


7?79 ~ 
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C.3 Memory Attributes [powerpc] 

The PowerPC architecture supports the following memory/cache attribute values, to be used with the MemoryControl 
system-call: 


attribute 

value 

Default 

0 

Write-through 

1 

Write-back 

2 

Caching-inhibited 

3 

Caching-enabled 

4 

Memory-global (coherent) 

5 

Memory-local (not coherent) 

6 

Guarded 

7 

Speculative 

8 


The default attributes enable write-back, caching, and speculation. Only if the kernel is compiled with support for multiple 
processors will memory coherency be enabled by default. 

The PowerPC architecture places a variety of restrictions on the usage of the memory/cache attributes. Some combina- 
tions are meaningless (such as combining write-through with caching-inhibited), or are not permitted and will lead to 
undefined behavior (for example, instruction fetching is incompatible with some combinations of attributes). The precise 
semantics of the memory/cache access attributes are described in the “Programming Environments Manual For 32-Bit 
Implementations of the PowerPC Architecture.” 

Before disabling the cache for a page, the software must ensure that all memory belonging to the target page is flushed 
from the cache. 


Generic Programming Interface 

#include <l4/misc.h> 

Word DefaultMemory 
Word WriteThroiigliMemory 
Word WriteBackMemory 
Word CachinglnhibitedMemory 
Word CachingEnabledMemory 
Word GlobalMemory 
Word LocalMemory 
Word GuardedMemory 
Word SpeculativeMemory 
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C.4 Exception Message Format [powerpc] 


System Call Trap 

System Call Trap Message to Exception Handler 

MR 12 
MR n 
MR io 
MR 9 
MR 8 
MR 7 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 

When user code executes the PowerPC ’sc' instruction, the kernel delivers the system call trap message to the exception 
handler. The kernel preserves only partial user state when handling an ’sc’ instruction. State is preserved similarly to 
the SVR4 PowerPC ABI for function calls. The non-volatile registers are Rl, R2, R13. . . R31, CR2, CR3, CR4, LR, and 
FPSCR. The volatile registers are R0, R3. . . R12, CRO, CR1, CR5. . . CR7, CTR, and XER. Thread virtual registers may 
also be clobbered. 

Generic Traps 

Generic Trap Message To Exception Handler 
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MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 

The kernel synthesizes exception messages in response to architecture specific events. Some traps are handled by the 
kernel and therefore do not generate exception messages. The kernel preserves all user state, including thread virtual 
registers. 
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C.5 Processor Mirroring [powerpc] 

The kernel will expose the following supervisor instructions to all user level programs via emulation: MFSPR for the 
PVR, MFSPR and MTSPR for the DABR and other cpu-specific debug registers. 

The kernel will emulate the MFSPR and MTSPR instructions for accessing cpu-specific performance monitor registers 
on behalf of privileged tasks. The performance monitor registers are global, and not per-thread. 

The ExchangeRegisters system-call accesses the flags of the processor. The flags map directly to the PowerPC MSR 
register. The following bits may be read and modified by user applications: LE, BE, SE, FEO, and FE1. The kernel also 
exposes additional cpu-specific bits. 
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C.6 Booting [powerpc] 


Apple New World Compatible Machines 

L4 must be loaded into memory at the physical location defined by the kernel’s ELF header. It can be started with virtual 
addressing enabled or disabled. Execution of L4 must begin at the entry point defined by the kernel's ELF header. 

When entering the kernel, the registers which support in-register file parameter passing. R3-R10 according to the SVR4 
ABI, must be cleared for upwards compatibility, except as noted below. All other registers in the register file are undefined 
at kernel entry. 

The kernel may use OpenFirmware for debug console I/O. To support OpenFirmware I/O, the OpenFirmware virtual 
mode client call-back address must be passed to the kernel in register R5, and OpenFirmware must be prepared to handle 
client call-backs using virtual addressing. In all other cases, register R5 must be zero. 

The boot loader must copy the OpenFirmware device tree to memory, and record its physical location in a memory 
descriptor of the kernel interface page. The copy of the device tree must include the package handles of the device tree 
nodes 



Appendix D 

PowerPC64 Interface 
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D.1 Virtual Registers [powerpc64] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the ppc64-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB is identical to the thread’s local ID. and is thus immutable. 
Setting the UTCB address of an active thread via ThreadControl is similar to deletion and re-creation. There is a 
fixed correlation between the UtcbLocation parameter when invoking ThreadControl and the UTCB address. The 
UTCB address is provided in the abi thread register r!3 at application start. UTCB objects of the current thread can 
then be accessed as any other memory object. UTCBs of other threads must not be accessed, even if they are physically 
accessible. ThreadWordO and ThreadWordl are free to be used by systems software (e.g., IDL compilers). The kernel 
associates no semantics with these words. 


ThreadWord 1 (64) 

ThreadWordO (54) 

~ (48) co P flags (8) preempt flags (8) 

ProcessorNo ( 64 ) 

VirtualSender/ActualSender (54) 

IntendedReceiver (54) 

ErrorCode ( 64 ) 

XferTimeouts (54) 

UserDefinedHandle (54) 

ExceptionHandler ( 64 ) 

Pager (64) 

MyGloballd ( 64 ) 


+ 88 
+ 80 
+72 
+64 
+56 
+48 
+40 
+32 
+24 
+ 16 
+8 

< — UTCB address 


MyLocalld = UTCB address (<;■}) 


r 1 3 


The TCR MyLocalld is not part of the UTCB. On PowerPC64 it is identical with the UTCB 
address and can be loaded from register r!3. 


Message Registers (MRs) 

Message registers MR o through MR g map to local registers in the processor’s general purpose register file for IPC and 
LIPC calls, otherwise they are located in the UTCB. The remaining message registers map to memory locations in the 
UTCB. MRq starts at byte offset 512 in the UTCB, and successive message registers follow in memory. 
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r23 

r22 

r21 

r20 

rl9 

rl8 

rl7 

rl6 

rl5 

rl4 


+ 1016 


< — UTCB address + 512 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BRo is at byte offset 248 in the UTCB, BR i at byte offset 
256, etc. 

BR o 32 [UTCB fields] 

+504 


+256 

<■ — UTCB address + 248 


BR 


32 ( 64 ) 


BR 1 ( 64 ) 


BR 


0 ( 64 ) 


UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 80. . . UTCB address + 247. The appli- 
cation can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the memory 
contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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D.2 Systemcalls [powerpc64] 


The system-calls which are invoked by the bctrl or instruction take the target of the calls from the system call link fields 
in the kernel interface page (see page 2). Each system-call link value specifies an address relative to the kernel interface 
page's base address. One may invoke the system calls with any instruction that branches to the appropriate target, as long 
as the return-address is contained in Ir. 

The locations of the system-calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the KIP. 

The system call definitions below only specify the contexts of the general purpose registers. Except for the KernelIn- 
TERFACE system-call, the contents of user accessible state registers are assumed to be scratched. The floating-point 
registers are assumed to be preserved accross system calls. 


KERNELlNTERFACE [Slow Systemcall] 


rO. . . r2 
r3 
r4 
r5 

— r6 

r7 . . . r31 
Ir 

— ctr 

— cr 

— xer 


— Kemellnterface — 


tibia 


r0...r2 

— 

r3 

KIP base address 

r4 

API Version 

r5 

API Flags 

r6 

Kernel ID 

r7. . . r31 

= 

Ir 

= 

ctr 

= 

cr 

= 

xer 

= 


For this system-call, all registers other than the output registers are preserved. 


EXCHANGEREGISTERS [Systemcall] 


- 

rO 

— Exchange Registers — * 

rO 

~ 

- 

rl 


rl 

= 

- 

r2 


r2 

= 

dest 

r3 

bctrl 

r3 

result 

control 

r4 


r4 

control 

SP 

r5 


r5 

SP 

IP 

r6 


r6 

IP 

FLAGS 

r7 


r7 

FLAGS 

UserDefinedHandle 

r8 


r8 

UserDefinedHandle 

pager 

r9 


r9 

pager 

isLocal 

rlO 


rlO 

isLocal 

- 

rll, rl2 


rll, rl2 


UTCB 

rl3 


rl3 

UTCB 

- 

rl4. . . r29 


rl4. . . r29 


- 

r30, r31 


r30, r31 

= 

- 

Ir 


Ir 


ExchangeRegisters 

ctr 


ctr 


- 

cr 


cr 


- 

xer 


xer 



“FLAGS” refers to the user- modifiable powerpc64 processor flags that are held in the msr register. 
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THREADCONTROL [Privileged Systemcall] 


rO 

— Thread Control — > 

rO ~ 

rl 


rl = 

r2 


r2 = 

dest r3 

bctrl 

r3 result 

space r4 


r4 ~ 

scheduler r5 


r5 rsj 

pager r6 


r6 

UtcbLocation r7 


r7 ~ 

r8. . . rl2 


r8. . . rl2 ~ 

UTCB rl3 


rl3 UTCB 

rl4. . . r29 


rl4 . . . r29 ~ 

r30, r31 


r30, r31 = 

Ir 


Ir ~ 

ThreadControl ctr 


ctr 

— cr 


cr 

— xer 


xer ~ 

SYSTEMCLOCK [Systemcall] 


rO 

— SystemClock — > 

rO ~ 

rl 


rl = 

r2 


r2 = 

r3 

bctrl 

r3 clock 

r4. . . rl2 


r4. . . rl2 ~ 

UTCB rl3 


rl3 UTCB 

rl4. . . r29 


rl4. . . r29 ~ 

r30, r31 


r30, r31 = 

Ir 


Ir ~ 

SystemClock ctr 


ctr ~ 

— cr 


cr 

— xer 


xer ~ 

THREADSWITCH [Systemcall] 


rO 

— ThreadSwitch — > 

rO ~ 

rl 


rl = 

r2 


r2 = 

dest r3 

bctrl 

r3 ~ 

r4... rl2 


r4. . . rl2 ~ 

UTCB rl3 


rl3 UTCB 

rl4. . . r29 


rl4 . . . r29 ~ 

r30, r31 


r30, r31 = 

Ir 


Ir ~ 

ThreadSwitch ctr 


ctr 

— cr 


cr ~ 

— xer 


xer ~ 
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Schedule [Systemcaii] 


- 

rO 

- 

rl 

- 

r2 

dest 

r3 

time control 

r4 

processor control 

r5 

priority 

r6 

preemption control 

r7 

- 

r8. . . rl2 

UTCB 

rl3 

- 

rl4. . . r29 

- 

r30, r31 

- 

Ir 

Schedule 

ctr 

- 

cr 

- 

xer 


— Schedule 

bctrl 


rO 


rl 

= 

r2 

= 

r3 

result 

r4 

time control 

r5 

~ 

r6 

~ 

r7 

~ 

r8. . . rl2 

~ 

rl3 

UTCB 

rl4. . . r29 

~ 

r30, r31 

= 

Ir 

~ 

ctr 

~ 

cr 



xer 


I PC [Systemcaii] 


- 

rO 

— Ipc — ► rO 


~ 

- 

rl 

rl 


= 

- 

r2 

r2 


= 

to 

r3 

bctrl r3 


from 

FromSpecifier 

r4 

r4 


~ 

Timeouts 

r5 

r5 


~ 

- 

r6. . . r!2 

r6 . . . 

. rl2 

~ 

UTCB 

rl3 

rl3 


UTCB 

MR o 

rl4 

rl4 


MR o 

MR-l 

rl5 

rl5 


MR i 

MR 2 

rl6 

rl6 


MR 2 

MR 3 

rl7 

rl7 


MR 3 

MR 4 

rl8 

rl8 


MR 4 

MR 5 

rl9 

rl9 


MR 5 

MR 6 

r20 

r20 


MR 6 

MR 7 

r21 

r21 


MR r 

MR 8 

r22 

r22 


MR 8 

MR g 

r23 

r23 


mr 9 

- 

r24. . . r29 

r24. 

. . r29 

~ 

- 

r30, r31 

r30, 

r31 

= 

- 

Ir 

Ir 


~ 

Ipc 

ctr 

ctr 



- 

cr 

cr 



- 

xer 

xer 
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LlPC [Systemcall] 


- 

rO 

— Lipc — > 

rO 

~ 

- 

rl 


rl 

= 

- 

r2 


r2 

= 

to 

r3 

bctrl 

r3 

from 

FromSpecifier 

r4 


r4 

~ 

Timeouts 

r5 


r5 

~ 

- 

r6. . . rl2 


r6. . . rl2 

~ 

UTCB 

rl3 


rl3 

UTCB 

MR o 

rl4 


rl4 

MR o 

MR i 

rl5 


rl5 

MR i 

MR 2 

rl6 


rl6 

MR 2 

MR 3 

r!7 


rl7 

MR 3 

MR 4 

rl8 


rl8 

MR 4 

MR 5 

rl9 


rl9 

MR s 

MR 6 

r20 


r20 

MR 6 

MR 7 

r21 


r21 

MR 7 

MR 8 

r22 


r22 

MR 8 

MR 9 

r23 


r23 

MR 9 

- 

r24. . . r29 


r24. . . r29 

~ 

- 

r30, r31 


r30, r31 

= 

- 

Ir 


Ir 

~ 

Lipc 

ctr 


ctr 


- 

cr 


cr 


- 

xer 


xer 



UNMAP [Systemcall] 


rO 

— Unmap — > 

rO ~ 

rl 


rl = 

r2 


r2 = 

control r3 

bctrl 

r3 ~ 

r4... rl2 


r4. . . rl2 ~ 

UTCB rl3 


rl3 UTCB 

rl4. . . r29 


rl4. . . r29 ~ 

r30, r31 


rJO, rJ7 = 

Ir 


Ir ~ 

Unmap ctr 


ctr ~ 

— cr 


cr ~ 

— xer 


xer ~ 


SPACECONTROL [Privileged Systemcall] 


- 

rO 

— Space Control — > 

rO 


- 

rl 


rl 

= 

- 

r2 


r2 

= 

SpaceSpecifier 

r3 

bctrl 

r3 

result 

control 

r4 


r4 

control 

KernellnterfacePageA rea 

r5 


r5 


UtcbArea 

r6 


r6 


Redirector 

r7 


r7 


- 

r8. . . rl2 


r8. . . rl2 


UTCB 

rl3 


rl3 

UTCB 

- 

rl4. . . r29 


rl4. . . r29 


- 

r30, r31 


r30, r31 

= 

- 

Ir 


Ir 


SpaceControl 

ctr 


ctr 


- 

cr 


cr 


- 

xer 


xer 
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PROCESSORCONTROL [Privileged Systemcall] 

- rO I — Processor Control 


- 

rO 

- 

rl 

- 

r2 

ProcessorNo 

r3 

InternalFreq 

r4 

ExternalFreq 

r5 

voltage 

r6 

- 

r7. . . rl2 

UTCB 

rl3 

- 

rl4. . . r29 

- 

r30, r31 

- 

Ir 

cessorControl 

ctr 

- 

cr 

- 

xer 


rO 

rl 

r2 

r3 

r4 

r5 

r6 

r7. . . rl2 
rl3 

rl4. . . r29 
r30, r31 
Ir 


MEMORYCONTROL [Privileged Systemcall] 

- rO — Memory Control 

rl 

r2 

control r3 bctrl 

attributeo r4 
attribute i r5 

attribute2 r6 
attribute 3 r7 

r8. . . rl2 

UTCB rl3 

rl4. . . r29 
r30, r31 
Ir 

MemoryControl ctr 


rO ~ 

rl = 

r2 = 

r3 res 

r4 ~ 

r5 ~ 

r6 ~ 

r7 rsj 

r8 . . . rl2 ~ 

rl3 UJ 

rl4. . . r29 ~ 

r30, r31 = 

Ir ~ 

ctr ~ 
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D.3 Memory Attributes [powerpc64] 


The powerpc64 architecture supports the following memory/cache attribute values, to be used with the MemoryCon- 
TROL system-call: 


attribute 

value 

Default 

0 

Uncached 

1 

Coherent 

2 


The default attributes depend on the platform and not all modes are defined for all processors. 
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DA Exception Message Format [powerpc64] 


System Call Trap 


System Call Trap Message to Exception Handler 

MR 12 
MR 11 
MR io 
MR 9 
MR 8 
MR 7 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 

When user code executes the PowerPC sc instruction, the kernel delivers the system call trap message to the exception 
handler. The kernel preserves only partial user state when handling a sc instruction. State is preserved similarly for the 
inclusive set of saved registers according the the 64-bit PowerPC elf ABI for function calls. 

The non-volatile registers are: rl, r2, rl3 . . . r31, CR2 . . . CR4 

The volatile registers are: rO, r3 ... rl2, LR. CTR, XER, CRO, CR1, CR5 . . .CR7 

Thread virtual registers may also be clobbered. 


Flags (64) 

SP (64) 

IP (64) 

r0 (64) 

rlO (64) 

r9 (64) 

r8 (64) 

r7 (64) 

r6 (64) 

r5 (64) 

r4 (64) 

r 3 (64) 

-5 ( 44 ) 0 ( 4 ) t = 0 ( 6 ) U = 12 ( 6 ) 


Generic Traps 


Generic Trap Message To Exception Handler 
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MR 7 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 


The kernel synthesizes exception messages in response to architecture specific events. Some traps are handled by the 
kernel and therefore do not generate exception messages. Exceptions that provide an error address use the ErrorAddress 
register and specify 7 Untyped words, otherwise only 6 Untyped words will be sent. The kernel preserves all user state, 
including thread virtual registers. 

For some exceptions, The following is a table of values for the Generic Trap ExceptionNo : 


Exception 

ExceptionNo 

ErrorCode 

Delivered 

ErrorAddress 

System Reset 

0x100 

- 

No 

- 

Machine Check 

0x200 

- 

No 

- 

DSI 

0x300 

DSISR 

If not paging related 

Yes 

ISI 

0x400 

- 

If not paging related 

No 

Interrupt 

0x500 

- 

No 

No 

Alignment 

0x600 

DSISR 

Yes 

Yes 

Program 

0x700 

- 

Yes 

Yes 

FPU Unavailable 

0x800 

- 

No 

- 

Decrementer 

0x900 

- 

No 

- 

System Call 

OxcOO 

- 

No 

- 

Trace 

OxdOO 

- 

If kdb not using 

No 

FPU Assist 

OxeOO 

- 

Yes 

No 

Performance 

OxfOO 

- 

Yes 

No 

Breakpoint 

0x1300 

- 

Yes 

No 

Soft Patch 

0x1500 

- 

Yes 

No 

Maintenance 

0x1600 

- 

Yes 

No 

Instrumentation 

0x2000 

- 

Yes 

No 


Note, not all of these exceptions will be delivered via exception IPC. Some will be handled by the kernel. Delivered 
exceptions are indicated in the last column of the table above. 
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D.5 Booting [powerpc64] 


IBM OpenFirmware Machines 

L4 must be loaded into memory at the physical location defined by the kernel’s ELF header. It can be started with virtual 
addressing enabled or disabled. Execution of L4 must begin at the entry point defined by the kernel's ELF header. 

When entering the kernel, the registers which support in-register file parameter passing, R3-R10 according to the Open- 
Power ABI, must be cleared for upwards compatibility, except as noted below. All other registers in the register file are 
undefined at kernel entry. 

The kernel may use OpenFirmware for debug console I/O. To support OpenFirmware I/O, the OpenFirmware virtual 
mode client call-back address must be passed to the kernel in register R5, and OpenFirmware must be prepared to handle 
client call-backs using virtual addressing???. In all other cases, register R5 must be zero. 

The boot loader must copy the OpenFirmware device tree to memory, and record its physical location in a memory 
descriptor of the kernel interface page. The copy of the device tree must include the package handles of the device tree 
nodes 



Appendix E 


Alpha Interface 



142 


VIRTUAL REGISTERS 


E.1 Virtual Registers [alpha] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the Alpha-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB is identical to the thread’s local ID. and is thus immutable. 
The UTCB (and hence local ID) is available through the rdunique PAL call. UTCB objects of the current thread can 
be accessed as any other memory object. UTCBs of other threads must not be accessed, even if they are physically 
accessible. 

+88 
+80 
+72 
+64 
+56 
+48 
+40 
+32 
+24 
+ 16 
+8 

< — UTCB 


calLpal rdunique 

The TCR MyLocalld is not part of the UTCB. On Alpha it is identical with the UTCB address 
and can be found using the rdunique PAL call. 


Message Registers (MRs) 

Message registers MR o through MR s map to the processor’s general purpose register file for IPC and LIPC calls. The 
remaining message registers map to memory locations in the UTCB. MR 9 starts at byte offset 200 in the UTCB, and 
successive message registers follow in memory. 

For the other system calls, message registers map to memory locations in the UTCB. with MRo starting at byte offset 
128. 
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s5 

s4 

s3 

s2 

si 

sO 

t7 

16 

s6 


+632 

+224 

+216 

+208 

<■ — UTCB address + 200 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BRo is at byte offset 640 in the UTCB, BR i at byte offset 
648, etc. 


BR o 32 [UTCB fields] 



+896 


+648 

< — UTCB address + 640 


UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 128. . . UTCB address + 199. The 
application can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the 
memory contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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E.2 Systemcalls [alpha] 


The system-calls invoked via the ’jsr’ instruction are located in the kernel’s area of the virtual address space. Their precise 
locations are stored in the kernel interface page (see page 2). One may invoke the system calls with any instruction that 
branches to the appropriate target, as long as the return-address register (RA) contains the correct return address. 

The locations of the system-calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the kip. 

Unless explicitly stated, the kernel follows the Alpha calling convention for the system call interface. This means that 
arguments are passed in the aO - a5 registers and the result is placed in the vO register. All ‘s’ registers are preserved and 
all ‘t’ registers are undefined. The sp and ra registers are also preserved. 

All floating point registers are preserved across a system call. 

All other registers contain return values, are undefined, or may be preserved according to processor specific rules. 


KernelInterface 

[Slow Systemcall] 



_ 

vO 

— KernelInterface — > 

vO 

KIP base address 

0x4c34 754b4b4 95034 

aO 


aO 

API Version 

- 

al 


al 

API Flags 

- 

a2 

calLpal cserve 

a.2 

Kernel ID 

- 

a3 


a3 


- 

a4 


a4 

~ 


a5 


a5 


ExchangeRegisters 

[Systemcall] 



_ 

vO 

— Exchange Registers — > 

vO 

result 

dest 

aO 


aO 

control 

control 

al 


al 

SP 

SP 

a2 

jsr ra, ExchangeRegisters 

a2 

IP 

IP 

a3 


a3 

FLAGS 

FLAGS 

a4 


a4 

UserDefinedHandle 

UserDefinedHandle 

a5 


a5 

pager 

pager 

tl 


tl 


ThreadControl 

[Privileged Systemcall] 



_ 

vO 

— Thread Control — > 

vO 

result 

dest 

aO 


aO 


SpaceSpecifier 

al 


al 


Scheduler 

a2 

jsrra, ThreadControl 

a2 


Pager 

a3 


a3 


UtcbLocation 

a4 


a4 



a5 


a5 




SYSTEMCALLS 


145 


SYSTEMCLOCK [Systemcall] 

vO — SystemClock — > 

— aO 

— al 

— a2 jsr ra, SystemClock 

— a3 

— a4 

— a5 

Note that the SystemClock system call is currently UNIMPLEMENTED on Alpha. 


vO clock 

aO 

al 

a.2 r-sj 
a3 ~ 
a4 ~ 
a5 ~ 


THREADSWITCH [Systemcall] 

vO — ThreadSwitch — > 

dest aO 

— al 

— a2 jsr ra, ThreadSwitch 

— a3 

— a4 

— a5 

vO ~ 

aO 

al ~ 

a2 

a3 

a4 ~ 

a5 

Schedule [Systemcall] 




_ 

vO 

— Schedule — > 

vO 

result 

dest 

aO 


aO 

TimeControl 

TimeControl 

al 


al 


ProcessorControl 

a2 

jsr ra. Schedule 

a.2 

~ 

Priority 

a3 


a3 


Preemption Control 

a4 


a4 

~ 


a5 


a5 


IPC [Systemcall] 





_ 

vO 

— Ipc — > 

vO 

result 

dest 

aO 


aO 

~ 

source 

al 


al 


timeout 

a2 

jsr ra, Ipc 

a.2 

~ 

~ 

a3 


a3 


- 

a4 


a4 


- 

a5 


a5 


MR q 

s6 


s6 

MRq 

MR i 

t6 


t6 

MR i 

MR 2 

t7 


t7 

MR 2 

MR 3 

sO 


sO 

MR 3 

MR 4 

si 


si 

MR A 

MR 5 

s2 


s2 

MRq 

MR 6 

s3 


s 3 

MRq 

MR 7 

s4 


s4 

MR 7 

MR 8 

s5 


s5 

MR 8 
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LlPC [Systemcall] 


- 

vO 

— Lipc — > 

vO 

result 

dest 

aO 


aO 

~ 

source 

al 


al 


timeout 

a2 

jsr ra, Lipc 

a2 

~ 

- 

a3 


a3 


- 

a4 


a4 


- 

a5 


a5 


MR o 

s6 


s6 

MR o 

MR i 

t6 


t6 

MR i 

MR 2 

t7 


t7 

MR 2 

MR 3 

sO 


sO 

MR 3 

MR 4 

si 


si 

MR 4 

MR 5 

s2 


s2 

MR s 

MR 6 

s3 


s3 

MR 6 

MR 7 

s4 


s4 

MR 7 

MR 8 

s5 


s5 

MR s 

Note that on Alpha LIPC is not implemented: use IPC instead. 



UNMAP [Systemcall] 





_ 

vO 

— Unmap — > 

vO 


control 

aO 


aO 


- 

al 


al 


- 

a2 

jsr ra. Unmap 

a.2 

~ 

- 

a3 


a3 


- 

a4 


a4 

~ 


a5 


a5 


SPACECONTROL [Privileged Systemcall] 



_ 

vO 

— Space Control — > 

vO 

result 

SpaceSpecifier 

aO 


aO 

control 

control 

al 


al 


KIP Area 

a2 

jsr ra, SpaceControl 

a2 

~ 

UTCBArea 

a3 


a3 


Redirector 

a4 


a4 

~ 


a5 


a5 


ProcessorControl 

[Privileged Systemcall] 



_ 

vO 

— Processor Control — > 

vO 

result 

ProcessorNo 

aO 


aO 

~ 

control 

al 


al 


InternalFreq. 

a2 

jsr ra, ProcessorControl 

a.2 

~ 

ExternalFreq. 

a3 


a3 

~ 

voltage 

a4 


a4 

~ 

- 

a5 


a5 


Note that on Alpha the ProcessorControl system call is not implemented. 
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MEMORYCONTROL [Privileged Systemcall] 


- 

vO 

— Memory Control — > 

vO result 

control 

aO 


aO ~ 

attributeO 

al 


al 

attribute 1 

a2 

jsr ra, MemoryControl 

a2 

attribute2 

a3 


a3 

attribute3 

a4 


a4 ~ 

- 

a5 


a5 


Note that on Alpha the MemoryControl system call is not implemented: the memory attributes for a page are defined by 
the system, and cannot be controlled by the application (or kernel). 
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E.3 Booting [alpha] 


All SRM based machines 

L4 must be loaded at the virtual address defined in the ELF header (corresponding to the physical region of the virtual 
address space). The kernel also requires the bootloader to initialise some kernel data structures, so the supplied bootloader 
is recommended. 

The preferred method for booting the kernel is via BootP. Consult the SRM documentation for instructions on setting 
up SRM to boot a file from a remote host. 



Appendix F 

Ml PS-64 Interface 
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VIRTUAL REGISTERS 


F.1 Virtual Registers [mips-64] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the mips64-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB is identical to the thread’s local ID, and is thus immutable. The 
UTCB (and hence local ID) is available in the kO register. UTCB objects of the current thread can be accessed as any 
other memory object. UTCBs of other threads must not be accessed, even if they are physically accessible. 


ThreadWord 1 ( 64 ) 

ThreadWordO ( 54 ) 

VirtualSender/ActualSender ( 64 ) 

IntendedReceiver (g 4 ) 

ErrorCode ( 64 ) 

XferTimeouts ( 64 ) 

~ ( 48 ) co P flags ( 8 ) preempt flags (8) 

ExceptionHandler (g 4 ) 

Pager (64) 

UserDefinedHandle ( 64 ) 

ProcessorNo ( 64 ) 

MyGloballd ( 64 ) 


+88 
+80 
+72 
+64 
+56 
+48 
+40 
+32 
+24 
+ 16 
+8 

< — UTCB address 


MyLocalld = UTCB address ( 6 4 ) 


UTCB syscall 


The TCR MyLocalld is not part of the UTCB. On mips64 it is identical with the UTCB address 
and is always in the kO register. The register should be treated as read-only. If modified, the 
effects are undefined. 


Message Registers (MRs) 

Message registers MR o through MR a map to the processor’s general purpose register file for IPC and LIPC calls. The 
remaining message registers map to memory locations in the UTCB. MRg starts at byte offset 200 in the UTCB, and 
successive message registers follow in memory. 

The first nine message registers are mapped to the registers vl, sO to s7. MR 9. ..63 are mapped to memory in the UTCB. 
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vl 

sO 

si 

s2 

s3 

s4 

s5 

s6 

s7 


+632 


< — UTCB address + 200 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BRo is at byte offset 640 in the UTCB, BR i at byte offset 
648, etc. 


BR o 32 [UTCB fields] 

+896 


+648 

< — UTCB address + 640 



UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 128. . . UTCB address + 191. The 
application can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the 
memory contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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F.2 Systemcalls [mips- 64 ] 


The system-calls invoked via the jal instruction are located in the kernel’s area of the virtual address space. Their precise 
locations are stored in the kernel interface page (see page 2). One may invoke the system calls with any instruction that 
branches to the appropriate target, as long as the return-address register RA contains the correct return address. 

The locations of the system-calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the KIP. 

In general, the kernel follows the MIPS ABI64 calling convention for the system call boundary. This means that ar- 
guments are passed in the aO - a7 registers, and the result is placed in the vO register. All floating point registers are 
preserved across a system call. All other registers contain return values, are undefined, or may be preserved according to 
processor specific rules. 


KERNELlNTERFACE [Slow Systemcall] 


OxlFACECAl 1 14E1F64 at 

vO.vl 

— aO. . . a3 
tO 

tl 

t2 

t3 

t4. . . t7 

- sO... s7 
t8, t9 
gP> S P 

- s8 

— ra 


— Kernellnterface — 


opcode 0x07FFFFFF 


at 

— 


vO,vl 

= 


aO. . . a3 

= 


a4 

KIP 

base address 

a5 

API 

Version 

a6 

API 

Flags 

a7 

Kernel ID 

t4. . . t7 

= 


sO. . . s7 

= 


t8, t9 

= 


gP> S P 

— 


s8 

= 



ra 


For this system-call, all registers other than the output registers are preserved. 


EXCHANGEREGISTERS [Systemcall] 


- 

at 

— Exchange Registers — > 

at 


- 

vO 


vO 

result 

- 

vl 


vl 


dest 

aO 

jal ExchangeRegisters 

aO 

control 

control 

al 


al 

SP 

SP 

a2 


a2 

IP 

IP 

a3 


a3 

FLAGS 

FLAGS 

tO 


a4 

pager 

UserDefinedHandle 

tl 


a5 

UserDefinedHandle 

pager 

t2 


a6 


- 

t3 


a7 


- 

t4. . . t7 


t4. . . t7 


- 

sO . . . s7 


sO . . . s7 


- 

t8, t9 


t8, t9 


- 

gP 


gP 


- 

sp 


sp 

= 

- 

s8 


s8 

= 

- 

ra 


ra 
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THREADCONTROL [Privileged Systemcall] 


— at 

— Thread Control — > 

at 

vO 


vO result 

vl 


vl ~ 

dest aO 

jal ThreadControl 

aO 

space al 


al 

scheduler a2 


a2 

pager a3 


a3 

UTCB to 


a4 ~ 

tl... t3 


a5. . .a7 ^ 

t4... t7 


t4 . . . t7 ~ 

— sO... s7 


sO . . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gp ~ 

sp 


sp = 

- s8 


s8 = 

— ra 


ra 

SYSTEMCLOCK [Systemcall] 


— at 

— SystemClock — > 

at ~ 

vO 


vO clock 

- vl 


vl ~ 

— aO. . . a3 

jal SystemClock 

aO. . .a3 ~ 

- tO... t3 


a4. . .a7 

t4... t7 


t4. . . t7 ~ 

— sO... s7 


sO. . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gP ~ 

sp 


sp = 

- s8 


s8 = 

— ra 


ra ~ 

THREADSWITCH [Systemcall] 


— at 

— ThreadSwitch — > 

at 

vO, vl 


vO, vl ~ 

dest aO 


aO ~ 

— al. . . a3 

jal ThreadSwitch 

al. . .a3 ~ 

— tO... t3 


a4. ..a7 ~ 

t4... t7 


t4. . . t7 ~ 

— sO... s7 


sO. . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gp r , j 

sp 


sp = 

- s8 


s8 = 

— ra 


ra ~ 
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Schedule [Systemcaii] 


— at 

— Schedule — > 

at 

vO 


vO result 

vl 


vl ~ 

dest aO 

jal Schedule 

aO time control 

time control al 


al ~ 

processor control a2 


a2 ~ 

priority a3 


a3 ~ 

preemption control tO 


a4 ~ 

tl... t3 


a5. . .a7 ~ 

t4. . . t7 


t4. . . t7 ~ 

- sO... s7 


sO . . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gp ~ 

sp 


sp = 

- s8 


s8 = 

— ra 


ra 


I PC [Systemcaii] 


- 

at 

— Ipc — > 

at 


- 

vO 


vO 

result 

MR (0) 

vl 


vl 

MR (0) 

to 

aO 

jal Ipc 

aO 

~ 

FromSpecifier 

al 


al 

~ 

Timeouts 

a.2 


a2 

~ 

- 

a3 


a3 

~ 

- 

tO. . . t3 


a4 . . . a7 


- 

t4 . . . 


t4. . . t7 


MR i 

sO 


sO 

MR i 

MR 2 

si 


si 

MR 2 

MR 3 

s2 


s2 

MR 3 

MR 4 

s3 


s3 

MR 4 

MR 5 

s4 


s4 

MR 5 

MR 6 

s5 


s5 

MR 6 

MR 7 

s6 


s6 

MR 7 

MR 8 

s7 


s7 

MR 8 

- 

t8, t9 


t8, t9 

~ 

- 

gP 


gP 

~ 

- 

sp 


sp 

= 

- 

s8 


s8 

— 

- 

ra 


ra 

~ 
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LlPC [Systemcall] 


- 

at 

— Lipc — > 

at 


- 

vO 


vO 

result 

- 

vl 


vl 


to 

aO 

jal Lipc 

aO 


FromSpecifier 

al 


al 

~ 

Timeouts 

a2 


a2 

~ 

- 

a3 


a3 

~ 

- 

tO. . . t3 


a4. . . a7 

~ 

- 

t4. . . t7 


t4. . . t7 

~ 

MR o 

sO 


sO 

MR o 

MR i 

si 


si 

MR i 

MR 2 

s2 


s2 

MR 2 

MR 3 

s3 


s3 

MR 3 

MR 4 

s4 


s4 

MR 4 

MR 5 

s5 


s 5 

MR 5 

MR & 

s6 


s6 

6 

MR 7 

s7 


s7 

Mi? 7 

- 

t8, t9 


t8, t9 

~ 

- 

gP 


gP 


- 

sp 


sp 

= 

- 

s8 


s8 

= 

- 

ra 


ra 

~ 


UNMAP [Systemcall] 

— at 

vO, vl 

control aO 

— al. . . a3 

- tO... t3 

t4. . . t7 

- sO... s7 

t8, t9 

gP 

sp 

- s8 

— ra 

— Unmap — > 

jal Unmap 

at 

vO, vl ~ 

aO 

al. . .a3 

a4. . .a7 ~ 

t4. . . t7 rsj 

sO. . . s7 ~ 

t8, t9 ~ 

gp ~ 

sp = 

s8 = 

ra ~ 

SPACECONTROL [Privileged Systemcall] 


— at 

— Space Control — > 

at ~ 

vO 


vO result 

vl 


vl ~ 

SpaceSpecifier aO 

jal SpaceControl 

aO control 

control al 


al 

KernellnterfacePageArea a2 


a2 r -~ / 

UtcbArea a3 


a3 

Redirector tO 


a4 ~ 

tl... t3 


a5. . .a7 ~ 

t4. . . t7 


t4. . . t7 ~ 

- sO... s7 


sO. . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gp ~ 

sp 


sp = 

- s8 


s8 = 

— ra 


ra ~ 
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PROCESSORCONTROL [Privileged Systemcall] 


— at 

— Processor Control — > 

at 

vO 


vO result 

vl 


vl ~ 

processor no aO 

jal ProcessorControl 

aO ~ 

InternalFreq al 


al 

ExternalFreq a.2 


a2 ~ 

voltage a3 


a3 ~ 

— tO... t3 


a4. . .a7 

t4... tl 


t4 . . . t7 ~ 

— sO... s7 


sO . . . s7 ~ 

t8, t9 


t8, t9 ~ 

gP 


gp ~ 

sp 


sp = 

- s8 


s8 = 

— ra 


ra ~ 


MEMORYCONTROL [Privileged Systemcall] 


- 

at 

— Memory Control — > 

at 

- 

vO 


vO result 

- 

vl 


vl ~ 

control 

aO 

jal MemoryControl 

aO ~ 

attributeo 

al 


al 

attribute \ 

a2 


a2 

attribute2 

a3 


a3 

attribute 3 

tO 


a4 ~ 

- 

tl. . . t3 


a5. . .a.7 ~ 

- 

t4. . . t7 


t4. . . t7 ~ 

- 

sO . . . s7 


sO. . . s7 ~ 

- 

t8, t9 


t8, t9 ~ 

- 

gP 


gP ~ 

- 

sp 


sp = 

- 

s8 


sS = 

- 

ra 


ra ^ 
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F.3 Memory Attributes [mips-64] 


The mips64 architecture supports the following memory/cache attribute values, to be used with the MemoryControl 
system-call: 


attribute 

value 

Default 

0 

Uncached 

1 

Write-back 

2 

Write-through 

3 

Write-through (no allocate) 

4 

Coherent 

5 

Flush-I (Flush instruction cache) 

30 

Flush-D (Flush data cache) 

31 


The default attributes depend on the platform and not all modes are defined for all processors. 

Before disabling the cache for a page, the software must ensure that all memory belonging to the target page is flushed 
from the cache. 
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F.4 Exception Message Format [mips-64] 


System Call Trap 


System Call Trap Message to Exception Handler 

MR 13 
MR 12 
MR ii 
MR io 
MR 9 
MR 8 
MR- 
MRo 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 

When user code executes the Mips syscall instruction, the kernel delivers the system call trap message to the exception 
handler. The kernel preserves only partial user state when handling a syscall instruction. State is preserved similarly for 
the inclusive set of saved registers according the the MIPS ABI 64,n32,o32 for function calls. 

The non-volatile registers are: sO ... s7, gp, sp, fp/s8 

The volatile registers are: AT. vO. vl, aO . . . a7, t4 ... t9, kO, kl, ra, hi, lo 

Thread virtual registers may also be clobbered. 


Flags (64) 

SP (64) 

IF (64) 

a7/t3 (64) 

a 6 /t 2 ( 64 ) 

a5/tl ( 64 ) 

a4/t0 ( 64 ) 

a 3 (64) 

a2 (64) 

al (64) 

aO (64) 

vl (64) 

CO 

O 

> 

-5 (44) 0 (4) t. = 0 (6) U = 13 (6) 


Generic Traps 


Generic Trap Message To Exception Handler 
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MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 


The kernel synthesizes exception messages in response to architecture specific events. Some traps are handled by the 
kernel and therefore do not generate exception messages. The kernel preserves all user state, including thread virtual 
registers. 

The following is a table of values for the Generic Trap ExceptionNo : 


Exception 

ExceptionNo 

ErrorCode 

Delivered 

Interrupt 

0 

- 

No 

TLB Write Denied 

1 

- 

No 

TLB Miss Load 

2 

- 

No 

TLB Miss Store 

3 

- 

No 

Address Error (load/execute) 

4 

BadVAddress 

Yes 

Address Error (store) 

5 

BadVAddress 

Yes 

Bus Error (instruction) 

6 

- 

Yes 

Bus Error (data) 

7 

- 

Yes 

System Call 

8 

- 

vO > 0 

Break Point 

9 

- 

!(-l 1 1 > AT > -100) 

Reserved Instruction 

10 

Instruction 

AT 7^ MAGIC KIP REQUEST 

Coprocessor Unavailable 

11 

Cause Register 

CPO, CP2, CP3 

Arithmetic Overflow 

12 

- 

Yes 

Trap 

13 

- 

Yes 

Virtual Coherency (instruction) 

14 

- 

Yes 

Floating Point 

15 

- 

Yes 

Watch Point 

23 

- 

Unless used by kdb 

Virtual Coherency (data) 

31 

- 

Yes 


Note, not all of these exceptions will be delivered via exception IPC. Some will be handled by the kernel. Delivered 
exceptions are indicated in the last column of the table above. 
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F.5 Booting [mips- 64 ] 


The kernel is provided as an ELF file and must be loaded according to the load addresses defined in the ELF header 
(corresponding to the physical region of the virtual address space). The kernel must be started in 64bit mode. 



Appendix G 

AMD64 Interface 
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G.1 Virtual Registers [amd64] 


Thread Control Registers (TCRs) 

TCRs are implemented as part of the amd64-specific user-level thread control block (UTCB). The address of the current 
thread's UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active thread via THREAD- 
CONTROL is similar to deletion and re-creation. There is a fixed correlation between the UtcbLocation parameter when 
invoking ThreadControl and the UTCB address. The UTCB address of the current thread can be loaded through a 
machine instruction 

mov %gs:[0], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must 
not be accessed, even if they are physically accessible. ThreadWordO and ThreadWordl are free to be used by systems 
software (e.g., IDL compilers). The kernel associates no semantics with these words. 


ThreadWordO ( 54 ) 

ThreadWord 1 ( 64 ) 

VirtualSender/ActualSender ( 54 ) 

IntendedReceiver (g 4 ) 

XferTimeouts ( 54 ) 

ErrorCode ( 64 ) 

~ ( 48 ) co P flags ( 8 ) preempt flags (8) 

ExceptionHandler (g 4 ) 

Pager (64) 

UserDefinedHandle ( 54 ) 

ProcessorNo ( 54 ) 

MyGloballd ( 64 ) 


< — UTCB address - 32 

- 40 

- 48 

- 56 

- 64 

- 72 

- 80 
- 88 
- 96 
-104 
-112 
-120 


MyLocalld = UTCB address 


gs:[0] 


The TCR MyLocalld is not part of the UTCB. On amd64 it is identical with the UTCB address 
and can be loaded from memory location gs:[0]. 


Message Registers (MRs) 

Memory-mapped MRs are implemented as part of the amd64-specific user-level thread control block (UTCB). The ad- 
dress of the current thread’s UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active 
thread via ThreadControl is similar to deletion and re-creation. There is a fixed correlation between the UtcbLoca- 
tion parameter when invoking THREADCONTROL and the UTCB address. The UTCB address of the current thread can 
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be loaded through a machine instruction 
mov %gs:[0], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must not 
be accessed, even if they are physically accessible. 

The first 8 message registers MRo through MR 7 are always mapped to general register. MRs ...63 are always mapped to 
memory. 


MR 0...7 


MR 7 


MR 6 


MR 5 


MR 4 


MR 3 


MR 2 


MR 1 


MR 0 


R15 

R14 

R13 

R12 

RIO 

RBX 

RAX 

R09 


MR 8 ... 63 [UTCB fields] 

+ 456 


+ 80 
+ 72 

< — UTCB address + 64 


MR 63 ( 64 ) 



Buffer Registers (BRs) 

BRs are implemented as part of the amd64-specific user-level thread control block (UTCB). The address of the current 
thread's UTCB will not change over the lifetime of the thread. Setting the UTCB address of an active thread via THREAD- 
CONTROL is similar to deletion and re-creation. There is a fixed correlation between the UtcbLocation parameter when 
invoking ThreadControl and the UTCB address. The UTCB address of the current thread can be loaded through a 
machine instruction 

mov %gs:[0], %r 

UTCB objects of the current thread can then be accessed as any other memory object. UTCBs of other threads must not 
be accessed, even if they are physically accessible. 


BR 0 32 [UTCB fields] 
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G.2 Systemcalls [amd64] 


The system-calls which are invoked by the call instruction take the target of the calls the from system-call link fields in 
the kernel interface page (see page 2). Each system-call link specifies an address relative to the kernel interface page’s 
base address. An application may use instructions other than call to invoke the system-calls, but must ensure that a valid 
return address resides on the stack. 


KERNELlNTERFACE [Slow Systemcall] 


RAX 

— Kernellnterfaee — ► 

rax base address 

RCX 


RCX API Version 

RDX 


RDX API Flags 

RSI 

lock: nop 

RSI Kernel ID 

RDI 


RDI = 

RBX 


RBX = 

RBP 


RBP = 

R08 


R08 = 

R09 


R09 = 

RIO 


RIO = 

Rll 


Rll = 

R12 


R12 = 

R13 


R13 = 

R14 


R14 = 

R15 


R15 = 

RSP 


RSP = 

ExchangeRegisters 

[Systemcall] 


dest rax 

— Exchange Registers — > 

rax result 

RCX 


RCX ~ 

SP RDX 


RDX SP 

control RSI 

call ExchangeRegisters 

RSI control 

pager RDI 


RDI pager 

RBX 


RBX ~ 

RBP 


RBP ~ 

IP R08 


R08 IP 

FLAGS R09 


R09 FLAGS 

UserDefinedHandle RIO 


RIO UserDefinedHandle 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

- R15 


R15 ~ 

RSP 


RSP ~ 

“FLAGS” refers to the user-modifiable amd64 processor flags that are held in the RFLAGS register. 
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THREADCONTROL [Privileged Systemcall] 


RAX 

— Thread Control — > 

rax result 

RCX 


RCX ~ 

scheduler rdx 


RDX ~ 

pager RSI 

call TlireadControl 

RSI ~ 

dest rdi 


RDI ~ 

RBX 


RBX ~ 

RBP 


RBP ~ 

SpaceSpecifier R08 


R08 ~ 

UTCBLocation R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

R15 


R15 ~ 

RSP 


RSP ~ 

SYSTEMCLOCK [Systemcall] 


RAX 

— SystemClock — > 

RAX clock 

RCX 


RCX ~ 

RDX 


RDX ~ 

RSI 

call SystemClock 

RSI ~ 

RDI 


RDI ~ 

RBX 


RBX ~ 

RBP 


RBP ~ 

R08 


R08 ~ 

R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

- R15 


R15 ~ 

RSP 


RSP ~ 

THREADSWITCH [Systemcall] 


RAX 

— ThreadSwitch — > 

RAX ~ 

RCX 


RCX ~ 

RDX 


RDX ~ 

RSI 

call ThreadSwitch 

RSI ~ 

dest RDI 


RDI ~ 

RBX 


RBX ~ 

RBP 


RBP ~ 

R08 


R08 ~ 

R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

R15 


R15 ~ 

RSP 


RSP ~ 
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Schedule [Systemcaii] 


RAX 

— Schedule — > 

rax time control 

RCX 


RCX ~ 

time control rdx 


RDX ~ 

prio rsi 

call Schedule 

RSI ~ 

dest RDI 


RDI ~ 

RBX 


RBX ~ 

RBP 


RBP ~ 

processor control R08 


R08 ~ 

preemption control R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

R15 


R15 ~ 

RSP 


RSP ~ 

IPC [Systemcaii] 


MR 1 RAX 

— Ipc — > 

RAX MR 1 

RCX 


RCX ~ 

FromSpecifier rdx 


RDX ~ 

to RSI 

call Ipc 

RSI from 

UTCB rdi 


RDI = 

MR 2 RBX 


RBX MR 2 

RBP 


RBP ~ 

Timeouts R08 


R08 ~ 

MR o R09 


R09 MR 0 

MR 3 RIO 


RIO MR 3 

Rll 


Rll ~ 

MR 4 , R 12 


R12 MR 4 

MR 5 R13 


R13 MR 5 

MR 6 R14 


R14 MR q 

MR 7 R15 


R15 MR 7 

RSP 


RSP ~ 

Ll PC [Systemcaii] 


MR 1 RAX 

— Lipc — > 

RAX MR 1 

RCX 


RCX ~ 

FromSpecifier RDX 


RDX ~ 

to RSI 

call Lipc 

RSI from 

UTCB rdi 


RDI = 

MR o RBX 


RBX MR 2 

RBP 


RBP ~ 

Timeouts R08 


R08 ~ 

MR o R09 


R09 MR o 

MR 3 RIO 


RIO MR 3 

Rll 


Rll ~ 

MR 4 , R 12 


R12 MR 4 

MR 5 R13 


R13 MR 5 

MR 6 R14 


R14 MR q 

MR 7 R15 


R15 MR 7 

RSP 


RSP ~ 
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UNMAP [Systemcall] 


MR i 

RAX 

— Unmap — ► 

RAX 

MR i 

- 

RCX 


RCX 


control 

RDX 


RDX 

~ 

~ 

RSI 

call Unmap 

RSI 

~ 

UTCB 

RDI 


RDI 

= 

MR 2 

RBX 


RBX 

MR 2 

- 

RBP 


RBP 

~ 

- 

R08 


R08 

~ 

MR o 

R09 


R09 

MR o 

MR 3 

RIO 


RIO 

M/e 3 

- 

Rll 


Rll 

~ 

MR 4 

R12 


R12 

Mtf 4 

MR s 

R13 


R13 

Mi? 5 

MR 6 

R14 


R14 

mk 6 

MR 7 

R15 


R15 

mk 7 

- 

RSP 


RSP 

~ 


SPACECONTROL [Privileged Systemcall] 


- RAX 

— Space Control — > 

rax result 

RCX 


RCX ~ 

KernellnterfacePageArea RDX 


RDX control 

control RSI 

call SpaceControl 

RSI ~ 

SpaceSpecifier RDI 


RDI ~ 

- RBX 


RBX ~ 

- RBP 


RBP ~ 

UTCB Are a R08 


R08 ~ 

Redirector R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

- R15 


R15 ~ 

RSP 


RSP ~ 

PROCESSORCONTROL [Privileged Systemcall] 


RAX 

— Processor Control — > 

RAX result 

RCX 


RCX ~ 

ExternalFrequency RDX 


RDX ~ 

InternalFrequency RSI 

call Processor-Control 

RSI ~ 

ProcessorNo RDI 


RDI ~ 

RBX 


RBX ~ 

RBP 


RBP ~ 

voltage R08 


R08 ~ 

R09 


R09 ~ 

RIO 


RIO ~ 

Rll 


Rll ~ 

R12 


R12 ~ 

R13 


R13 ~ 

R14 


R14 ~ 

R15 


R15 ~ 

RSP 


RSP ~ 
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MEMORYCONTROL [Privileged Systemcall] 


MR i 

RAX 

attribute o 

RCX 

control 

RDX 

attributei 

RSI 

UTCB 

RDI 

MR 2 

RBX 

- 

RBP 

attribute 2 

R08 

MR 0 

R09 

MR 3 

RIO 

attributes 

Rll 

MR 4 

R12 

MR 5 

R13 

MR 6 

R14 

MR 7 

R15 

- 

RSP 


— Memory Control — > 

call MemoryControl 


rax ~ 

RCX ~ 
RDX result 
RSI ~ 

RDI = 
RBX ~ 

RBP ~ 

R08 ~ 

R09 ~ 

RIO ~ 

Rll ~ 

R12 ~ 

R13 ~ 

R14 ~ 

R15 ~ 

RSP ~ 
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G.3 10-PortS [amd64] 


On AMD64 processors, IO-ports are handled as fpages. 10 fpages can be mapped, granted, and unmapped like memory 
fpages. Their minimal granularity is 1. An IO-fpage of size 2 s has a 2 s -aligned base address p, i.e. p mod 2 s =0. An 
fpage with base port address p and size 2 s is denoted as described below. 


IOfpage (p, 2 s ') 


P (16/48) 

S’ (6) 

s ~ 2 (6) 

0 rwx 


IO-ports can only be mapped idempotently, i.e., physical port x is either mapped at 10 address x in the task’s 10 address 
space, or it is not mapped at all. 


Generic Programming Interface 

#include <l4/space.h> 

Fpage IoFpage (Word BaseAddress, int FpageSize) 

Fpage IoFpageLog2 (Word BaseAddress, int LoglFpageSize < 64) 

Delivers an 10 fpage with the specified location and size. 
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G.4 Cacheability Hints [amd64] 

String items can specify cacheability hints to the kernel (see page 54). For amd64, the cacheability hints have the 
following semantics. 

hh — oq Use the processor’s default cacheability strategy. Typically, cache lines are allocated for data 
read and written (assuming that the processor’s default strategy is write-back and write-allocate). 

hh = 01 Allocate cache lines in the entire cache hierarchy for data read or written. 

hh = 10 Do not allocate new cache lines (entire cache hierarchy) for data read or written. 

hh — H Allocate only new LI cache line for data read or written. Do not allocate cache lines in lower 
cache hierarchies. 


Convenience Programming Interface 

#include <l4/ipc.h> 

CacheAllocationHint UseDefaultCacheLineAllocation 
CacheAllocationHint AllocateNewCacheLines 
CacheAllocationHint DoNotAllocateNewCacheLines 
CacheAllocationHint AllocateOnlyNewLl CacheLines 
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G.5 Memory Attributes [amd64] 


The AMD64 architecture in general supports the following memory attributes values. 


attribute 

value 

Default 

0 

Uncacheable 

1 

Write Combining 

2 

Write Through 

5 

Write Protected 

6 

Write Back 

7 


Note that some attributes are only supported on certain processors. See the “AMD64 Architecture Programmer’s Manual 
Volume 2: System Programming” for the semantics of the memory attributes and which processors they are supported 
on. 


Generic Programming Interface 

#include <l4/misc.h> 

Word DefaultMemory 
Word UncacheableMemory 
Word WriteCombiningMemory 
Word WriteThroughMemory 
Word WriteProtectedMemory 
Word WriteBackMemory 
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G.6 Exception Message Format [amd64] 


To Exception Handler 


ErrorCode 

ExceptionNo 

RFLAGS 

RSP 

Rll 

R09 

R08 

RBP 

RDI 

RSI 

RDX 

RCX 

RAX 

R15 

R14 

R13 

R12 

RIO 

RBX 

RIP 

-4/ - 5 (44) 0 (4) 0 (4) t = 0 ( 6 ) U = 20 (6) 


MR 20 
MR 19 
MR is 
MR i 7 
MR i6 
MR is 
MR 14 
MR 13 
MR 12 
MR n 
MR io 
MR 9 
MR s 
MR- 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR o 


#PF (page fault), #MC (machine check exception), and some #GP (general protection), #SS (stack segment fault), and 
#NM (no math coprocessor) exceptions are handled by the kernel and therefore do not generate exception messages. 

Note that executing an INT n instructions in 32 -bit mode will always raise a #GP (general protection). The exception 
handler may interpret the error code (8 n + 2 , see processor manual) and emulate the INT n accordingly. 
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G.7 Processor Mirroring [amd64] 


Segments 

L4 uses a flat (unsegmented) memory model. There are only three segments available: user^space, a read/write segment, 
user_space_exec, an executable segment, and utcb_address, a read-only segment. Both user_space and userjpace.exec 
cover (at least) the complete user-level address space. \Jtcb.address covers only enough memory to hold the UTCB 
address. 

The values of segment selectors are undefined. When a thread is created, its segment registers SS, DS, ES and FS 
are initialized with user_space , GS with utcb .address, and CS with user .space _exec. Whenever the kernel detects a 
general protection exception and the segment registers are not loaded properly, it reloads them with the above mentioned 
selectors. From the user's point of view, the segment registers cannot be modified. 

However, the binary representation of user^space and user jpace. exec may change at any point during program exe- 
cution. Never rely on any particular value. 

Furthermore, the LSL (load segment limit) machine instruction may deliver wrong segment limits, even floating ones. 
The result of this instruction is always undefined. 


Debug Registers 

User-level debug registers exist per thread. DRO. ..3, DR6 and DR7 can be accessed by the machine instructions 
mov n,DRx and mov DRx,r. However, only task-local breakpoints can be activated, i.e., bits GO. . . 3 in DR7 cannot be 
set. Breakpoints operate per thread. Breakpoints are signaled as #DB exception (INT 1). 

Note that user-level breakpoints are suspended when kernel breakpoints are set by the kernel debugger. 


Model-Specific Registers 

All privileged threads in the system have read and write access to all the Model-Specific Registers (MSRs) of the CPU. 
Modification of some MSRs may lead to undefined system behavior. Any access to an MSR by an unprivileged thread 
will raise an exception. 
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G.8 Booting [amd64] 


PC-compatible Machines 

L4 can be loaded at any 16-byte-aligned location beyond 0x1000 in physical memory. It can be started in real mode 
or in 32-bit protected mode at address 0x100 or 0x1000 relative to its load address. The protected-mode conditions are 
compliant to the Multiboot Standard Version 0.6. 


Start Preconditions 


Real Mode 

32-bit Protected Mode 

load base (L) 

L > 0x1000, 16-byte aligned 

L> 0x1000 

load offset (X) 

X = 0x100 or X = 0x1000 

X = 0x100 or X = 0x1000 

Interrupts 

disabled 

disabled 

Gate A20 

~ 

open 

EFLAGS 

1=0 

1=0, VM=0 

CR0 

PE=0 

PE=1, PG=0 

(E)IP 

X 

L + X 

CS 

L/ 16 

0. 4GB, 32-bit exec 

SS.DS.ES 


0, 4GB, read/write 

EAX 


0x2BADB0O2 

EBX 


*P 

(P + 0) 


~ OR 1 

(P + 4> 

n/a 

below 640 K mem in K 

(P + 8) 


beyond 1M mem in K 

all remaining registers & flags 



(general, floating point, 



ESP, xDT, TR, CRx, DRx) 




L4 relocates itself to 0x1000, enters protected mode if started in real mode, enables paging and initializes itself. 
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VIRTUAL REGISTERS 


H.1 Virtual Registers [sparc v9] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the sparc64-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB is identical to the thread’s local ID. and is thus immutable. 
Setting the UTCB address of an active thread via ThreadControl is similar to deletion and re-creation. There is a 
fixed correlation between the UtcbLocation parameter when invoking ThreadControl and the UTCB address. The 
UTCB address is provided in the general purpose register g7 at application start. UTCB objects of the current thread can 
then be accessed as any other memory object. UTCBs of other threads must not be accessed, even if they are physically 
accessible. ThreadWordO and ThreadWordl are free to be used by systems software (e.g., IDL compilers). The kernel 
associates no semantics with these words. 


ThreadWord 1 ( 64 ) 

ThreadWordO ( 54 ) 

~ (48) co P fla § s (8) preempt flags (8) 

ProcessorNo ( 54 ) 

VirtualSender/ActualSender ( 54 ) 

IntendedReceiver ( 64 ) 

ErrorCode ( 54 ) 

XferTimeouts ( 54 ) 

UserDefinedHandle ( 64 ) 

ExceptionHandler (g 4 ) 

Pager (64) 

MyGloballd ( 64 ) 


+ 88 
+ 80 
+72 
+64 
+56 
+48 
+40 
+32 
+24 
+16 
+8 

< — UTCB address 


MyLocalld = UTCB address ( 64 ) 


g7 


The TCR MyLocalld is not part of the UTCB. On SPARC v9 it is identical with the UTCB 
address and can be loaded from register g7. 


Message Registers (MRs) 

Message registers MR 0 through MR 7 map to the local registers of the current window in the processor’s general purpose 
register file for IPC and LIPC calls, otherwise they are located in the UTCB. The remaining message registers map to 
memory locations in the UTCB. MR 0 starts at byte offset 512 in the UTCB, and successive message registers follow in 
memory. 
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17 

16 

15 

14 

13 

12 

11 

10 


+ 1016 


< — UTCB address + 512 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BRo is at byte offset 248 in the UTCB, BR i at byte offset 
256, etc. 


BR o 32 [UTCB fields] 



+504 


+256 

<■ — UTCB address + 248 


UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 80. . . UTCB address + 247. The appli- 
cation can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the memory 
contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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H.2 Systemcalls [sparc-v9] 


The system-calls which are invoked by the jmpl instruction take the target of the calls from the system call link fields in 
the kernel interface page (see page 2). Each system-call link value specifies an address relative to the kernel interface 
page's base address. One may invoke the system calls with any instruction that branches to the appropriate target, as long 
as the return-address is contained in o7. 

The locations of the system-calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the KIP. 

The system call definitions below only specify the contexts of the general purpose registers. Except for the KernelIn- 
TERFACE system-call, the contents of user accessible state registers are assumed to be scratched. The floating-point 
registers are assumed to be preserved accross system calls. 


KERNELlNTERFACE [Slow Systemcall] 


gl . . . g7 — Kernellnterface — > 

00 

01 

— o2 ta 0x70 

— o3 

— o4 

10.. . 17 

10. . . i7 


gl-- 

■g7 

= 

oO 


KIP base address 

ol 


API Version 

o2 


API Flags 

o3 


Kernel ID 

o7 


= 

10 .. 

.17 

= 

iO.. 

.i7 

= 


EXCHANGEREGISTERS [Systemcall] 


- 

gl 

— Exchange Registers — > 

gl 


- 

g2,g3 


g2,g3 

= 

FLAGS 

g4 


gl 

FLAGS 

- 

g5’g6 

jmpl ExchangeRegisters 

g5 ,g 6 


UTCB 

g7 


g7 

UTCB 

dest 

oO 


oO 

result 

control 

ol 


ol 

control 

SP 

o 2 


o 2 

SP 

IP 

o3 


o3 

IP 

pager 

o4 


o4 

pager 

UserDefinedHandle 

o5 


o5 

UserDefinedHandle 

- 

06 , o7 


06 , o7 

= 

- 

10. . . 17 


10. . . 17 

= 

- 

iO. . . iO 


iO. . . iO 

= 


“FLAGS" refers to the user-modifiable flags held in the SPARC v9 PSTATE register. At present only the CLE (current 
little-endian) flag can be set. 
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THREADCONTROL [Privileged Systemcall] 


- gl 

— Thread Control — > 

gl 

- g2,g3 


g2,g3 = 

g4... g 6 


g4. . . g 6 ~ 

UTCB g 7 

jmpl ThreadControl 

K 7 UTCB 

dest oO 


oO result 

space ol 


ol ~ 

scheduler o 2 


o 2 ~ 

pager o3 


o3 ^ 

UtcbLocation o4 


o4 

o5 


o5 ~ 

— 06 , ol 


06 , o7 = 

10... 17 


10. ..17 = 

iO. . . \7 


iO. . . i7 = 

SYSTEMCLOCK [Systemcall] 


- gi 

— SystemClock — > 

gi 

- g2.g3 


g2.g3 = 

g4... g 6 


g4. . . g 6 ~ 

UTCB g 7 

jmpl SystemClock 

g7 UTCB 

oO 


oO clock 

— ol... o5 


ol. . .o5 ~ 

— 06 , o7 


06 , o7 = 

10... 17 


10. ..17 = 

iO. . . i7 


iO. . . i7 = 

THREADSWITCH [Systemcall] 


- gi 

- ThreadSwitch — ► 

gi 

- g2.g3 


g2.g3 = 

g4... g 6 


g4. ..g 6 ~ 

UTCB g 7 

jmpl ThreadSwitch 

g7 UTCB 

dest oO 


oO ~ 

— ol... o5 


ol. . .o5 ~ 

— 06 , o7 


06 , o7 = 

10... 17 


10. ..17 = 

iO. . . i7 


iO. . . i7 = 

Schedule [Systemcall] 



- gi 

— Schedule — > 

gi 

- g2.g3 


g2.g3 = 

g4... g 6 


g4. . . g 6 ~ 

UTCB g 7 

jmpl Schedule 

g7 UTCB 

dest oO 


oO result 

time control ol 


ol time control 

processor control o 2 


o 2 ~ 

priority o3 


o3 ~ 

preemption control o4 


o4 ~ 

— o5 


o5 ~ 

— 06 , o7 


06 , o7 = 

10... 17 


10. ..17 = 

iO. . . \7 


iO. . . i7 = 
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I PC [Systemcall] 


- 

gl 

— Ipc — > 

gl 


- 

g2,g3 


g2.g3 

— 

- 

g4. ■ ■ g 6 


g4 - . . g 6 


UTCB 

g? 

jmpl Ipc 

g7 

UTCB 

to 

oO 


oO 

from 

FromSpecifier 

ol 


ol 


Timeouts 

o 2 


o 2 


- 

o3. . . o5 


o3. . . o5 


- 

06 , o7 


06 , o7 

= 

MR o 

10 


10 

MR o 

MR i 

11 


11 

MR i 

MR 2 

12 


12 

MR 2 

MR 3 

13 


13 

MR 3 

MR 4 

14 


14 

MR 4 

MR 5 

15 


15 

MR 5 

MR 6 

16 


16 

MR 6 

MR 7 

17 


17 

MR 7 

- 

iO . . . i5 


iO. . . i5 



i 6 , i7 


i 6 , i7 


LlPC [Systemcall] 




- 

gl 

— Lipc — > 

gi 


- 

g2,g3 


g2,g3 

= 

- 

g4. ■ ■ g 6 


g4 - . . g 6 


UTCB 

g 2 

jmpl Lipc 

g7 

UTCB 

to 

oO 


oO 

from 

FromSpecifier 

ol 


ol 

no 

Timeouts 

o 2 


o 2 

no 

- 

o3. . . o5 


o3. . . o5 

no 

- 

06 , o7 


06 , o7 

= 

MR 0 

10 


10 

MR o 

MR i 

11 


11 

MR i 

MR 2 

12 


12 

MR 2 

MR 3 

13 


13 

MR 3 

MR 4 

14 


14 

MR 4 

MR 5 

15 


15 

MR s 

MR 6 

16 


16 

MR 6 

MR 7 

17 


17 

MR 7 

- 

iO. . . i5 


iO. . . i5 



i 6 , i7 


i 6 , i7 


UNMAP [Systemcall] 




- 

gi 

— Unmap — > 

gi 


- 

g2, g 3 


g2.g3 

= 

- 

g4- ■ ■ g 6 


g4- ■ ■ g 6 


UTCB 

g7 

jmpl Unmap 

g7 

UTCB 

control 

oO 


oO 


- 

ol. . . o5 


ol. . . o5 


- 

06 , o7 


06 , o7 

= 

- 

10. . . 17 


10. . . 17 

= 


iO. . . i7 


iO. . . i7 
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SPACECONTROL [Privileged Systemcall] 


- 

— Space Control — ► 

gl ~ 

- * 2 .gJ 


g2,g3 = 

g4- ■ ■ g6 


g4. ,.g6 ~ 

UTCB g 7 

jmpl SpaceControl 

g7 UTCB 

SpaceSpecifier oO 


oO result 

control ol 


ol control 

KernellnteifacePageArea o2 


o2 ~ 

UtcbArea o3 


o3 ~ 

Redirector o4 


o4 ~ 

- oS 


o5 ~ 

— 06, o7 


06 , o7 = 

10... 17 


/0. . . 17 = 

iO. . . i7 


iO. . . i7 = 


PROCESSORCONTROL [Privileged Systemcall] 


- 

— Processor Control — > 

gl 

- 


g2,g3 = 

** . . g6 


g4. . . g6 ~ 

UTCB g 7 

jmpl ProcessorControl 

g7 UTCB 

ProcessorNo oO 


oO result 

IntemalFreq ol 


ol ~ 

ExtemalFreq o2 


o2 ~ 

voltage o3 


o3 r -~ l 

— o4, o5 


o4, o5 ~ 

— 06, o7 


06, o7 = 

10... 17 


10. ..17 = 

— iO. . . i7 


iO. . . i7 = 


MEMORYCONTROL [Privileged Systemcall] 


- 

gl 

- 

g2,g3 

- 

g4. ■ ■ g6 

UTCB 

g? 

control 

oO 

attributeo 

ol 

attributei 

o2 

attribute2 

o3 

attribute^ 

o4 

- 

o5 

- 

06, o7 

- 

10. . . 17 

- 

iO. . . i7 


— Memory Control — > 


jmpl Memory Control 


gl 

g2,g3 = 

g4. . . g6 ~ 

g7 UTCB 

00 result 

01 ~ 

02 ~ 

03 ~ 

04 ~ 

05 ~ 

06 , o7 = 

10. ..17 = 

iO. . . i7 = 
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VIRTUAL REGISTERS 


1.1 Virtual Registers [arm] 


Thread Control Registers (TCRs) 

TCRs are mapped to memory locations. They are implemented as part of the ARM-specific user-level thread control 
block (UTCB). The address of the current thread’s UTCB will not change over the lifetime of the thread. The UTCB 
address of the current thread can be read from the memory location OxFFOOOOOO. UTCB objects of the current thread can 
then be accessed as any other memory object. UTCBs of other threads must not be accessed, even if they are physically 
accessible. 


ThreadWord 1 (32) 

ThreadWordO (32) 

VirtualSender/ActualSender ( 32 ) 

IntendedReceiver ( 32 ) 

ErrorCode ( 32 ) 

XferTimeouts (32) 

~ ( 16 ) co P flags (8) preempt flags (8) 

ExceptionHandler (32) 

Pager (32) 

UserDefinedHandle (32) 

ProcessorNo (32) 

MyGloballd 


+44 

+40 

+36 

+32 

+28 

+24 

+20 

+ 16 

+ 12 

+8 

+4 

< — UTCB address 


MyLocalld = UTCB address ( 32 ) 


UTCB syscall 


The TCR MyLocalld is not part of the UTCB. On ARM it is identical with the UTCB address 
and can be obtained by a load from memory location OxFFOOOOOOO. 


Message Registers (MRs) 

Message registers MR o through MR 4 map to the processor’s general purpose register file for IPC, LIPC and unmap calls. 
The remaining message registers map to memory locations in the UTCB. MR 5 starts at byte offset 84 in the UTCB, and 
successive message registers follow in memory. 

The first five message registers are mapped to the registers r3 to r7. MR 5. ..63 are mapped to memory in the UTCB. 
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r3 

r4 

r5 

r6 

r7 


+316 


< — UTCB address + 84 


Buffer Registers (BRs) 

The buffer registers map to memory locations in the UTCB. BRo is at byte offset 320 in the UTCB, BR i at byte offset 
324, etc. 


BR o 32 [UTCB fields] 



+448 


+324 

<■ — UTCB address + 320 


UTCB Memory With Undefined Semantics 

The kernel will associate no semantics with memory located at UTCB address + 452. .. UTCB address + 511. The 
application can use this memory as thread local storage, e.g., for implementing the L4 API. Note, however, that the 
memory contents within this region may be overwritten during a system-call operating on message registers. 

All undefined UTCB memory which is not covered by the above mentioned region may have kernel defined semantics. 
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1.2 Systemcalls [arm] 


The system-calls, which are invoked by the bl instruction, take the target of the calls from the system call link fields in the 
kernel interface page (see page 2). Each system-call link value specifies an address relative to the kernel interface page’s 
base address. One may invoke the system calls with any instruction that branches to the appropriate target, as long as the 
retum-address is contained in rl4. 

The locations of the system-calls are fixed during the life of an application, although they may change outside of the life 
of an application. It is not valid to prelink an application against a set of system call locations. The official locations are 
always provided in the KIP. 

The .sp and Zr registers are always preserved across system calls. Registers r8..rl2 have undefined values following 
system calls other than Kernellnterface. 


KERNELlNTERFACE [Slow Systemcall] 


rO 

— Kernellnterface — ► 

rO KIP base address 

rl 


rl API Version 

r2 


r2 API Flags 

r3 

bl 0xFE0000B4 

r3 Kernel ID 

r4 


r4 = 

r5 


r5 = 

r6 


r6 = 

r7 


r7 = 


For this system-call all registers other than the output registers are preserved. 


ExchangeRegisters 


[Systemcall] 


dest 

rO 

control 

rl 

SP 

r2 

IP 

r3 

FLAGS 

r4 

UserDefinedHandle 

r5 

pager 

r6 

- 

r7 


— Exchange Registers — > 

bl ExchangeRegisters 


rO 

result 

rl 

control 

r2 

SP 

r3 

IP 

r4 

FLAGS 

r5 

UserDefinedHandle 

r6 

pager 

r7 



THREADCONTROL [Privileged Systemcall] 


dest 

rO 

— Thread Control — > 

rO result 

space 

rl 


rl ~ 

scheduler 

r2 


r2 rsj 

pager 

r3 

bl ThreadControl 

r3 ~ 

UTCB 

r4 


r4 ~ 

- 

r5 


r5 ~ 

- 

r6 


r6 

- 

r7 


r7 rsj 
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SYSTEMCLOCK [Systemcall] 


- 

rO 

rl 

r2 

r3 

r4 

r5 

r6 

r7 

— SystemClock — > 

bl SystemClock 

rO 

rl 

r2 

r3 

r4 

r5 

r6 

r7 

clock 0..31 
clock 32.. 63 

THREADSWITCH [Systemcall] 



dest 

rO 

— ThreadSwitch — > 

rO 


- 

rl 


rl 


- 

r2 


r2 


- 

r3 

bl ThreadSwitch 

r3 


- 

r4 


r4 


- 

r5 


r5 


- 

r6 


r6 



r7 


r7 


Schedule [Systemcall] 




dest 

rO 

— Schedule —* 

rO 

result 

TimeControl 

rl 


rl 

TimeControl 

ProcessorControl 

r2 


r2 


priority 

r3 

bl Schedule 

r3 

~ 

Preemption Control 

r4 


r4 

~ 

- 

r5 


r5 


- 

r6 


r6 

~ 


r7 


r7 


IPC [Systemcall] 





dest 

rO 

— Ipc — ► 

rO 

result 

FromSpecifier 

rl 


rl 

~ 

Timeouts 

r2 


r2 

~ 

MRq 

r3 

bl I pc 

r3 

MRq 

MR i 

r4 


r4 

MR i 

mr 2 

r5 


r5 

MR 2 

mr 3 

r6 


r6 

mr 3 

mr 4 

r7 


r7 

MR, 

Ll PC [Systemcall] 





dest 

rO 

— Lipc — > 

rO 

result 

FromSpecifier 

rl 


rl 

~ 

Timeouts 

r2 


r2 

~ 

MRq 

r3 

bl Lipc 

r3 

MRq 

MR i 

r4 


r4 

MR, 

mr 2 

r5 


r5 

mr 2 

mr 3 

r6 


r6 

mr 3 

MR 3 

r7 


r7 

MR, 
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UNMAP [Systemcall] 

control 

rO 

— Unmap — > 

rO 


- 

rl 


rl 

~ 

- 

r2 


r2 

~ 

MR 0 

r3 

bl Unmap 

r3 

MR 0 

MR 1 

r4 


r4 

MR i 

MRo 

r5 


r5 

MR‘2 

mr 3 

r6 


r6 

mr 3 

mr 4 

r7 


r7 

MR 4 


SPACECONTROL [Privileged Systemcall] 



SpaceSpecifier 

rO 

— Space Control — > 

rO 

result 

control 

rl 


rl 

control 

KernellnteifacePageArea 

r2 


r2 

~ 

UtcbArea 

r3 

bl SpaceControl 

r3 

~ 

Redirector 

r4 


r4 

~ 

- 

r5 


r5 

~ 

- 

r6 


r6 

~ 


r7 


r7 


ProcessorControl 

[Privileged Systemcall] 



ProcessorNo 

rO 

— Processor Control — > 

rO 

result 

InternalFreq 

rl 


rl 

~ 

ExternalFreq 

r2 


r2 

~ 

voltage 

r3 

bl ProcessorControl 

r3 

~ 

- 

r4 


r4 

~ 

- 

r5 


r5 

~ 

- 

r6 


r6 

~ 


r7 


r7 



MEMORYCONTROL [Privileged Systemcall] 


control 

rO 

— Memory Control — > 

rO result 

attributed 

rl 


rl ~ 

attributei 

r2 


r2 ~ 

attribute2 

r3 

bl MemoryControI 

r3 ~ 

attributes 

r4 


r4 ~ 

- 

r5 


r5 ~ 

- 

r6 


r6 ~ 

- 

r7 


r7 ~ 
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1.3 Memory Attributes [arm] 

The ARM architecture supports the following memory/cache attribute values, to be used with the MemoryControl 
system-call: 


attribute 

value 

Default 

0 

Uncached 

1 

Flush (I + D) 

31 


The default memory attributes specify cached access. 

Before disabling the cache for a page, the software must ensure that all memory belonging to the target page is flushed 
from the cache. 
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1.4 Space Control [arm] 


The SpaceControl system call has an architecture dependent control parameter to specify various address space char- 
acteristics. For ARM, the control parameter has the following semantics. 


Input Parameter 


control 


0 ( 25 ) 


PID (7) 


Sets the PID register value that will be loaded for threads in this address space. The effect of this 
is described in the Fast Context Switch Extension section of the ARM Architecture Reference 
Manual. 

All addresses supplied to and returned from kernel syscalls (e.g. UTCB location) correspond to 
the MVA. 
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1.5 Exception Message Format [arm] 


Syscall emulation exception message 

MR 13 
MR 12 
MR n 
MR io 
MR 9 
MR 8 
MR 7 
MR 6 
MR 5 
MR 4 
MR 3 
MR 2 
MR i 
MR 0 


On execution of an ARM SWI instruction, the above message is delivered to the thread’s exception handler. 

The Syscall field contains the encoding of the instruction causing the system call exception. The exception handler can 
decode the system call number from the lower 24 bits. 


Flags ( 32 ) 

Syscall (32) 

LR (32) 

SP (32) 

r7 (32) 

r6 (32) 

r5 (32) 

r4 (32) 

r 3 (32) 

r2 (32) 

r * (32) 

r0 (32) 

(32) 

—5 (12) 0 ( 4 ) 0 ( 4 ) t- = 0(g) U = 13 (g) 
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1.6 Booting [arm] 


The kernel is provided as an ELF file and must be loaded at the physical load address defined in the ELF header. It must 
begin execution at the corresponding physically addressed entry point with MMU disabled. 



Appendix J 

Generic Bootlnfo 
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J.1 Generic Bootlnfo [Data Structure] 


The generic Bootlnfo structure contains boot loader specific data such as loaded modules or files, location of system 
tables, etc. The data structure can be located anywhere in memory, but must be aligned at a word size. 

The Bootlnfo structure is a pure boot loader specific object. That is, the kernel does not associate any semantics with 
its contents. A boot loader is free to choose whether to provide a Bootlnfo structure or not. Starting a system without a 
generic Bootlnfo structure is perfectly valid. 


First Bootlnfo Record 



Num Entries 

First Entry 

Size 

Version 

Magic 


+C/+18 +8/ +10 +4/ +8 +0 


First Entry 


+ 10/ +20 
Bootlnfo 


The base address of the bootinfo structure is specified by the Bootinfo field in the kernel interface page (see page 4). Note 
that the base address as specified by the Bootlnfo field is a physical address. An application running on virtual memory 
must determine the location of the Bootlnfo structure within its own address space by other means. 


Bootlnfo Description 


Magic 


Version 


Size 


The magic number 0xl4B0021D. The magic also determines the endianess of the structure (i.e., 
the value 0xlD02B014 indicates that the endian is wrong). The word size of the Bootlnfo 
structure is defined by the word size specified in the kernel interface page (see page 3). 

API version of the Bootlnfo structure. This document describes version 1 . Note that any changes 
in the Bootlnfo records themselves do not influence the version in the main Bootlnfo structure. 
This enables Bootlnfo records to be added or modified without introducing major incompatibili- 
ties with a program that parses the Bootlnfo structure. Only the added/modified Bootlnfo record 
types are influenced by the update. 

The size (in bytes) of the complete Bootlnfo structure, including all Bootlnfo records and data 
referenced by these records. 


First Entry Points to the first Bootlnfo record. First Entry is given as an address relative to the base address 

of the Bootlnfo structure itself. 


Num Entries Number of Bootlnfo records in the Bootlnfo structure. 


Generic Bootlnfo Record 

The exact structure of a Bootlnfo record is determined by the type of the record. Only the three 
first words of the record are defined for all Bootlnfo record types. 


Offset Next 


Version 


Type 


+ 8/ +10 


+4/ +8 


+0 


Type 


Specifies the type of the Bootlnfo record. 
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Version Specifies the API version of the Bootlnfo record type. Increasing the version of a Bootlnfo 

record type does not also require an increase in the main Bootlnfo version. Later versions of a 
Bootlnfo record are guaranteed to be backwards compatible with older versions. 

Offset Next The offset (in bytes) to the next Bootlnfo record. Note that the offset may vary from record to 

record, even for records of the same type. This enables the boot loader to have variable length 
records, place data in between records, or otherwise align records for ease of implementation. 
It is wrong to assume that the offset associated with a particular version of a record type is 
constant. 


Convenience Programming Interface 


#include <l4/bootinfo.h> 
struct BootRec { Word raw[*] } 


Bool Bootlnfo -Valid (void* Bootlnfo) 

Checks whether specified Bootlnfo structure is valid or not (i.e., whether the magic number and 
the version number are correct). 

Word Bootlnfo Size (void* Bootlnfo) 

Delivers the size (in bytes) of the Bootlnfo structure. It is assumed that Bootlnfo specifies a valid 
Bootlnfo structure. 

BootRec* Bootlnfo _FirstEntry (void* Bootlnfo) 

Delivers the first Bootlnfo record of the Bootlnfo structure. It is assumed that Bootlnfo specifies 
a valid Bootlnfo structure. 

Word Bootlnfo -Entries (void* Bootlnfo) 

Delivers the number of Bootlnfo records in the Bootlnfo structure. It is assumed that Bootlnfo 
specifies a valid Bootlnfo structure. 

Word Type (BootRec* BootRec) [BootRec -Type} 

Delivers the type of the Bootlnfo record. 

BootRec* Next (BootRec* BootRec) [BootRec -Next] 

Delivers the next Bootlnfo record. The value returned by the last Bootlnfo record in the Bootlnfo 
structure is undefined. 
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J.2 Bootlnfo Records [Bootlnfo] 


Bootlnfo records can be listed in any order. This section lists currently defined Bootlnfo records. A program encountering 
an unknown Bootlnfo record can skip past the record using the ubiquitous Offset Next field. 


Simple Module 


Start 


The Simple Module Bootlnfo record specifies a binary file loaded into main memory by the 
boot loader. 



Cmdline Off 

Size 

Start 

Offset Next 

version = 1 

type = 0x1 

+C/+18 

+8/ +10 

+4/ +8 

+0 


Physical address of first byte in loaded module. 


Size Size of loaded module (in bytes). 

Cmdline Off Address of command line associated with loaded module, or 0 if no command line exists. Ad- 

dress is specified relative to base address of current Bootlnfo record. 


Simple Executable The Simple Executable Bootlnfo record specifies an executable file which has been loaded into 
main memory and relocated by the boot loader. The record can only specify simple executables 
with single code, data, and bss sections. 

+30 / +60 
+20 / +40 
+ 10/ +20 


Pstart Physical address of first byte in code/data/bss section of the loaded executable. 

1 /start Virtual address of first byte in code/data/bss section of the loaded executable. 


Cmdline Off 

Label 

Flags 

Initial IP 

Bss. Size 

Bss.Vstart 

Bss.Pstart 

Data. Size 

Data.Vstart 

Data.Pstart 

Text. Size 

Text.Vstart 

Text.Pstart 

Offset Next 

version = 1 

type = 0x2 


+C/+18 +8/ +10 +4/ +8 +0 


Size 


Size of code/data/bss section (in bytes). 


Initial IP Virtual address of entry point for loaded executable. 

Flags Flags for the loaded executable (defined by boot loader or application programs). Note that 

regular applications may not necessarily have write permissions on the Flags field. 

Pabgl Freely available word (defined by boot loader or application programs). Note that regular appli- 

cations may not necessarily have write permissions on the Label field. 


Cmdline Off Address of command line associated with loaded executable, or 0 if no command line exists. 

Address is specified relative to base address of current Bootlnfo record. 
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EFI Tables 


The EFI Tables Bootlnfo record specifies the location and size of the EFI memory map, and the 
location of the EFI system table. 


Systab 
Memmap 
Memmap Size 
Memdesc Size 
Memdesc Version 


Memdesc Version 

Memdesc Size 

Memmap Size 

Memmap 

Systab 

Offset Next 

version = 1 

type = 0x101 

+C/+18 

+8/ +10 

+4/ +8 

+0 


Physical address of EFI system table, or 0 if EFI system table is not present. 

Physical address of EFI memory map. Undefined if Memmap Size = 0. 

Size (in bytes) of the EFI memory map, or 0 if EFI memory map is not present. 

Size (in bytes) of descriptor entries in the EFI memory map. Undefined if Memmap Size = 0. 
Version of descriptor entries in the EFI memory map. Undefined if Memmap Size = 0. 


Multiboot info The Multiboot info Bootlnfo record specifies the location of the first byte in the multiboot header. 


Multiboot Addr 

Offset Next 

version = 1 

type = 0x102 

+C/+18 

+8/ +10 

+4/ +8 

+0 


Multiboot Addr Physical address of first byte in multiboot header. 


Convenience Programming Interface 

#include <l4/bootinfo.h> 

Word Bootlnfo .Module 
Word Bootlnfo SimpleExec 
Word Bootlnfo JiFITables 
Word Bootlnfo JMuItiboot 

Word Module Start ( BootRec * b) 

Word Module Size {BootRec* b) 

Delivers the start and size of the specified boot module. 

char* Module Cmdline (BootRec* b) 

Delivers the command line of the specified boot module, or 0 if command line does not exist. 

Word SimpleExec TextPstart (BootRec* b ) 

Word SimpleExec CTextV start (BootRec* b ) 

Word SimpleExec CTextSize (BootRec* b) 

Word SimpleExec DataPstart (BootRec* b) 

Word SimpleExec _DataVstart (BootRec* b) 

Word SimpleExec DataSize (BootRec* b) 

Word SimpleExec BssPstart (BootRec* b) 

Word SimpleExec Jiss V start (BootRec* b) 
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Word SimpleExec _BssSize (BootRec* b) 

Delivers physical start address, virtual start address, and size of the code/data/bss section of the 
specified executable. 

Word SimpIeExecJnitiallP ( BootRec * b) 

Delivers virtual address of entry point for the specified executable. 

Word SimpIeExec_FIags ( BootRec * b) 

void SimpleExec _Set_FIags ( BootRec * b, Word w) 

Delivers/sets the flags field for the specified executable. 

Word SimpleExec _Label (BootRec* b) 

void SimpleExec _Set_Label (BootRec* b, Word w) 

Delivers/sets the label field for the specified executable. 

char* SimpleExec JCmdline (BootRec* b) 

Delivers the command line of the specified executable, or 0 if command line does not exist. 

Word EFIJSystab (BootRec* b ) 

Delivers the EFI system table, or 0 if system table not present. 

Word EE! Meinmap (BootRec* b) 

Word EE! MeininapSiz.e (BootRec* b) 

Word EFI MemdescSize (BootRec* b) 

Word EFI Menulesc Version (BootRec* b) 

Delivers location of the EFI memory map, size of memory map, size of memory map descriptor 
entries, and version of memory map descriptor entries. If EFlJdemmapSize () delivers 0, the 
other return values are undefined. 

Word MBI Address (BootRec* b) 

Delivers the physical location of the first byte in the multiboot header. 
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Development Remarks 


These remarks illuminate the design process from version 2 to version 4. 

K.1 Exception Handling 

The current model decided upon for exception handling in L4 is to associate an exception handler thread with each thread 
in the system (see page 68). This model was chosen because it allowed us to handle exceptions generically without 
introducing any new concepts into the API. It also closely resembles the current page fault handling model. 

Another model for exception handling is to use callbacks. Using this model an instruction pointer for a callback 
function and a pointer to an exception state save area is associated with each thread. Upon catching an exception the 
kernel stores the cause of the exception into the save area and transfers execution to the exception callback function. 

It is evident that the callback model can be faster than the IPC model because the callback model may require only 
one control transfer into the kernel whereas the IPC model will require at least two. Nevertheless, the IPC model was 
chosen because it introduces no new mechanisms into the kernel, and we are currently not aware of any real life sce- 
nario where the extra performance gain you very much. There exists a challenge to prove these claims wrong. See 
http://14hq.org/fun/ for the rules of the challenge. 
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APPENDIX K. DEVELOPMENT REMARKS 



Table of Procs, Types, and Constants 


used system call page 


! = (CacheAllocationHint 1, r) Bool 

—none— 

56 

! = (Clock 1, r) Bool 

—none— 

26 

! = (MsgTag 1, r) Bool 

—none— 

48 

! = (Threadld 1, r) Bool 

-none- 

15 

! = (Time 1, r) Bool 

—none— 

29 

+ (Acceptor 1, r) Acceptor 

-none- 

57 

+ (Clock 1, int r) Clock 

—none— 

26 

+ (Clock 1, Word64 r) Clock 

—none— 

26 

+ (Fpage f. Word AccessRights) Fpage 

-none- 

37 

+ (MsgTag t. Word label) MsgTag 

-none- 

48 

+ (Stringltem s, CacheAllocationFlint h) Stringltem 

-none- 

56 

+ (Time 1. r) Time 

-none- 

29 

+ (Time 1, Word r) Time 

—none— 

29 

+ = (Acceptor 1, r) Acceptor 

—none— 

57 

+ = (Fpage f. Word AccessRights) Fpage 

-none- 

37 

+ = (MsgTag t. Word label) MsgTag 

—none— 

48 

+ = (Stringltem& dest, Stringltem AdditionalSubstring) Stringltem & 

-none- 

55 

+ = (Stringltem& dest, void* AdditionalSubstringAddress) Stringltem & 

—none— 

55 

+ = (Stringltem s, CacheAllocationFlint h) Stringltem 

—none— 

56 

+ = (Time 1, r) Time 

-none- 

29 

+ = (Time 1, Word r) Time 

—none— 

29 

— (Acceptor 1, r) Acceptor 

-none- 

57 

— (Clock 1, int r) Clock 

—none— 

26 

- (Clock 1, Word64 r) Clock 

—none— 

26 

— (Fpage f. Word AccessRights) Fpage 

-none- 

37 

— (Time 1, r) Time 

-none- 

29 

— (Time 1. Word r) Time 

-none- 

29 

— = (Acceptor 1, r) Acceptor 

—none— 

57 

— = (Fpage f. Word AccessRights) Fpage 

—none— 

37 

— = (Time 1, r) Time 

—none— 

29 

— = (Time 1, Word r) Time 

-none- 

29 

< (Clock 1, r) Bool 

—none— 

26 

< (Time 1. r) Bool 

-none- 

29 

<= (Clock 1, r) Bool 

—none— 

26 

<= (Time 1, r) Bool 

—none— 

29 

== (CacheAllocationFlint 1, r) Bool 

-none- 

56 

== (Clock 1, r) Bool 

—none— 

26 

== (MsgTag 1, r) Bool 

-none- 

48 

== (Threadld 1, r) Bool 

—none— 

15 

== (Time 1, r) Bool 

—none— 

29 

> (Clock 1, r) Bool 

-none- 

26 

> (Time 1, r) Bool 

-none- 

29 

>= (Clock 1, r) Bool 

-none- 

26 

>= (Time 1, r) Bool 

—none— 

29 

AbortIpc_and_stop (Threadld t) ThreadState 

ExchangeRegisters 

21 

AbortIpc_and_stop (Threadld t, Word& sp, ip, flags) ThreadState 

ExchangeRegisters 

21 

AbortReceive_and_stop (Threadld t) ThreadState 

ExchangeRegisters 

21 

AbortReceive_and_stop (Threadld t, Word& sp, ip, flags) ThreadState 

ExchangeRegisters 

21 

AbortSend_and_stop (Threadld t) ThreadState 

ExchangeRegisters 

21 
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used system call 

page 

AbortSend and stop (Threadld t, Word& sp, ip, flags) ThreadState 

ExchangeRegisters 

21 

Accepted () Acceptor 

—none— 

58 

Acceptor data type 

-n/a— 

57 

Accept (Acceptor a) void 

-none- 

58 

Accept (Acceptor a, MsgBuffer& b) void 

-none- 

58 

ACPIMemoryType Word const 

-n/a— 

115 

ActualSender () Threadld 

—none— 

17 

ActualSender () Threadld 

-none- 

65 

Address (Fpage f) Word 

-none- 

37 

AllocateNewCacheLines CacheAllocationHint const 

-n/a- 

171 

AllocateNewCacheLines CacheAllocationHint const 

—n/a— 

97 

AllocateOnlyNewLlCacheLines CacheAllocationHint const 

-nJa- 

171 

AllocateOnlyNewLlCacheLines CacheAllocationHint const 

-n/a- 

97 

anylocalthread Threadld const 

-n/a— 

15 

anythread Threadld const 

-n/a- 

15 

ApiFlags () Word 

-none- 

8 

ApiVersion () Word 

-none- 

8 

Append (MsgBuffer& b, Stringltem * s) void 

—none— 

58 

Append (MsgBuffer& b, Stringltem s) void 

-none- 

58 

Append (Msg& msg, Grantltem g) void 

-none- 

49 

Append (Msg& msg, Mapltem m) void 

-none- 

49 

Append (Msg& msg, Stringltem& s) void 

-none- 

49 

Append (Msg& msg, Stringltem s) void 

—none— 

49 

Append (Msg& msg, Word w) void 

-none- 

49 

ArchitectureSpecificMemoryType Word const 

-n/a- 

9 

Associatelnterrupt (Threadld InterruptThread, InterruptHandler) Word 

—none— 

24 

Bootlnfo JiFITables Word const 

-n/a- 

199 

Bootlnfo-Entries (void* Bootlnfo) Word 

—none— 

197 

BootInfo_FirstEntry (void* Bootlnfo) BootRec* 

-none— 

197 

Bootlnfo-Module Word const 

-n/a— 

199 

Bootlnfo JMultiboot Word const 

-n/a- 

199 

BootInfo_SimpleExec Word const 

-n/a- 

199 

BootInfo_Size (void* Bootlnfo) Word 

-none- 

197 

Bootlnfo.Yalid (void* Bootlnfo) Bool 

-none— 

197 

Bootlnfo (void* Kernellnterface) Word 

-none- 

9 

BootLoaderSpecificMemoryType Word const 

-n/a- 

9 

BootRec data type 

-n/a— 

197 

CacheAllocationFIint (Stringltem s) CacheAllocationHint 

-none- 

56 

CacheAllocationHint data type 

-n/a- 

55 

CacheNonTemporalAllLevels CacheAllocationHint const 

-n/a— 

113 

CacheNonTemporalLl CacheAllocationHint const 

-n/a— 

113 

CacheNonTemporalL2 CacheAllocationHint const 

-n/a— 

113 

CachingEnabledMemory Word const 

-n/a- 

124 

CachinglnhibitedMemory Word const 

-n/a- 

124 

Call (Threadld to) MsgTag 

Ipc 

63 

Call (Threadld to. Time SndTimeout, RcvTimeout) MsgTag 

Ipc 

64 

Clear (MsgBuffer& b) void 

—none— 

58 

Clear (Msg& msg) void 

-none- 

49 

Clock data type 

-n/a- 

26 

Or CopFlag (Word n) void 

-none- 

17 

Clr_CopFlag (Word n) void 

-none- 

69 

CompleteAddressSpace Fpage const 

-n/a- 

37 

CompundString (Stringltem& s) Bool 

-none- 

55 

ConventionalMemoryType Word const 

-n/a— 

9 

Deassociatelnterrupt (Threadld InterruptThread) Word 

—none— 

24 

DedicatedMemoryType Word const 

-n/a- 

9 

DefaultMemory Word const 

-n/a— 

114 

DefaultMemory Word const 

-n/a— 

124 

DefaultMemory Word const 

-n/a- 

172 

DefaultMemory Word const 

-n/a- 

73 

DefaultMemory Word const 

-n/a— 

98 

DisablePreemptionFaultException () Bool 

-none— 

34 

DisablePreemption () Bool 

-none- 

34 
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page 

DoNotAlloeateNewCacheLines CacheAllocationHint const 

-n/a- 

171 

DoNotAlloeateNewCacheLines CacheAllocationHint const 

-n/a- 

97 

EFIJVIemdescSize (BootRec* b) Word 

-none- 

200 

EFIJMemdesc Version (BootRec* b) Word 

-none- 

200 

EFIJMemmapSize (BootRec* b) Word 

—none— 

200 

EFIJMemmap (BootRec* b) Word 

-none- 

200 

EFI Systab (BootRec* b) Word 

—none— 

200 

EnablePreemptionFaultException () Bool 

-none- 

34 

EnablePreemption () Bool 

—none— 

34 

ErrlnvalidParam Word const 

-n/a- 

33 

ErrlnvalidParam Word const 

-n/a- 

73 

ErrlnvalidScheduler Word const 

-n/a- 

24 

ErrlnvalidSpace Word const 

—n/a— 

24 

ErrlnvalidSpace Word const 

-n/a— 

43 

ErrlnvalidThread Word const 

—n/a— 

21 

ErrlnvaiidThread Word const 

—n/a— 

24 

ErrlnvalidThread Word const 

-n/a- 

33 

ErrKipArea Word const 

-n/a- 

43 

ErrNoMem Word const 

-n/a- 

24 

ErrNoPrivilege Word const 

-n/a- 

24 

ErrNoPrivilege Word const 

—n/a— 

33 

ErrNoPrivilege Word const 

-n/a- 

43 

ErrNoPrivilege Word const 

—n/a— 

71 

ErrNoPrivilege Word const 

—n/a— 

73 

ErrorCode () Word 

-none- 

17 

ErrorCode () Word 

—none— 

21 

ErrorCode () Word 

-none- 

24 

ErrorCode () Word 

—none— 

33 

ErrorCode () Word 

-none- 

43 

ErrorCode () Word 

-none- 

64 

ErrorCode () Word 

—none— 

71 

ErrorCode () Word 

-none- 

73 

ErrUtcbArea Word const 

—n/a— 

24 

ErrUtcbArea Word const 

—n/a— 

43 

ExceptionHandler () Threadld 

-none- 

17 

ExceptionHandler () Threadld 

—none— 

68 

ExchangeRegisters (Threadld dest. Word control, sp, ip, flags, UserDe- 
finedHandle, Threadld pager, Word& old_control, old_sp, old_ip, old_flags, 
old.UserDefinedHandle, Threadld& old_pager) Threadld 

ExchangeRegisters 

20 

executable Word const 

-n/a- 

37 

ExternalFreq (ProcDesc& p) Word 

-none- 

10 

Feature (void* Kernellnterface, Word num) char* 

—none— 

9 

Flush (Fpage f) Fpage 

Unmap 

40 

Flush (Word n, Fpage& [n] fpages) void 

Unmap 

40 

FpageLog2 (Word BaseAddress, int Log2FpageSize < 64) Fpage 

-none- 

37 

Fpage (Word BaseAddress, int FpageSize > IK) Fpage 

-none- 

37 

Fpage data type 

-n/a- 

36 

Fully Accessible Word const 

-n/a- 

37 

GetStatus (Fpage f) Fpage 

—none— 

40 

Get (Msg& msg, Word& ut, {Mapltem, Grantltem, Stringltem}& Items) void 

-none- 

49 

Get (Msg& msg. Word t, Grantltem& g) Word 

-none- 

50 

Get (Msg& msg. Word t, Mapltem& m) Word 

—none— 

50 

Get (Msg& msg. Word t, Stringltem& s) Word 

—none— 

50 

Get (Msg& msg. Word u) Word 

-none- 

50 

Get (Msg& msg. Word u, Word& w) void 

—none— 

50 

Globalld (Threadld t) Threadld 

ExchangeRegisters 

15 

Globalld (Threadld t) Threadld 

ExchangeRegisters 

20 

Globalld (Word threadno, version) Threadld 

—none— 

15 

GlobalMemory Word const 

-n/a- 

124 

Grantltem (Fpage f. Word SndBase) Grantltem 

—none— 

53 

Grantltem (Grantltem g) Bool 

-none- 

53 

Grantltem data type 

—n/a— 

53 

GuardedMemory Word const 

-n/a- 

124 
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page 

High (MemoryDesc& m) Word 

-none- 

9 

IntendedReceiver () Threadld 

—none— 

17 

IntendedReceiver () Threadld 

-none- 

64 

InternalFreq (ProcDesc& p) Word 

-none- 

10 

IoFpageLog2 (Word BaseAddress, int Log2FpageSize < 64) Fpage 

-none- 

170 

IoFpageLog2 (Word BaseAddress, int Log2FpageSize < 64) Fpage 

-none- 

95 

IoFpage (Word BaseAddress, int FpageSize) Fpage 

—none— 

170 

IoFpage (Word BaseAddress, int FpageSize) Fpage 

-none- 

95 

IpcFailed (Msg Tag t) Bool 

-none- 

64 

IpcPropagated (Msg Tag t) Bool 

—none— 

64 

IpcRedirected (Msg Tag t) Bool 

-none- 

64 

IpcSucceeded (Msg Tag t) Bool 

-none- 

64 

IpcXcpu (Msg Tag t) Bool 

-none- 

64 

Ipc (Threadld to, FromSpecifier, Word Timeouts, Threadld& from) MsgTag 

Ipc 

63 

IsGloballd (Threadld t) Bool 

—none— 

15 

IsLocalld (Threadld t) Bool 

-none- 

15 

IsNilFpage (Fpage f) Bool 

-none- 

37 

IsNilThread (Threadld t) Bool 

—none— 

15 

Is Virtual (MemoryDesc& m) Bool 

-none- 

9 

KernelGenDate (void* Kernellnterface, Word& year, month, day) void 

—none— 

8 

Kernelld () Word 

—none— 

8 

Kernellnterface () void* 

KernelInterface 

8 

Kernellnterface (Word& ApiVersion, ApiFlags, Kernelld) void * 

KernelInterface 

8 

KernelSupplier (void* Kernellnterface) Word 

-none- 

8 

KernelVersionString (void* Kernellnterface) char* 

-none- 

9 

KernelVersion (void* Kernellnterface) Word 

—none— 

8 

KipAreaSizeLog2 (void* Kernellnterface) Word 

—none— 

9 

Label (Msg& msg) Word 

—none— 

49 

Label (Msg Tag t) Word 

-none- 

48 

LargeSpace Word const 

-n/a- 

96 

Lcall (Threadld to) MsgTag 

LlPC 

64 

Lipc (Threadld to. FromSpecifier, Word Timeouts, Threadld& from) MsgTag 

Lipc 

63 

LoadBRs (int i, k, Word& [fc]) void 

-none- 

11 

LoadBRs (int i, k, Word& [fc]) void 

-none- 

58 

LoadBR (int i. Word w) void 

-none- 

11 

LoadBR (int i. Word w) void 

—none— 

58 

LoadMRs (int i, k, Word& [fc] w ) void 

-none- 

11 

LoadMRs (int i, k, Word& [fc] w ) void 

-none- 

50 

LoadMR (int i. Word w ) void 

—none— 

11 

LoadMR (int i. Word w ) void 

-none- 

50 

Load (Msg& msg) void 

-none- 

49 

Localld (Threadld t) Threadld 

ExchangeRegisters 

15 

Localld (Threadld t) Threadld 

ExchangeRegisters 

20 

LocalMemory Word const 

-n/a- 

124 

Low (MemoryDesc& m) Word 

-none- 

9 

LreplyWait (Threadld to, Threadld& from) MsgTag 

LlPC 

64 

MapGrantltems (Acceptor a) Bool 

—none— 

58 

MapGrantltems (Fpage RcvWindow) Acceptor 

-none- 

57 

Mapltem (Fpage f, Word SndBase) Mapltem 

-none- 

51 

Mapltem (Mapltem m) Bool 

-none- 

52 

Mapltem data type 

-n/a- 

51 

MBI Address (BootRec* b) Word 

—none— 

200 

MemoryControl (Word control, Word& attributes[4]) Word 

MemoryControl 

73 

MemoryDesc (void* Kernellnterface, Word num) MemoryDesc* 

-none- 

9 

MemoryDesc data type 

-n/a- 

8 

Module Cmdline (BootRec* b) char* 

-none- 

199 

Module _Size (BootRec* b) Word 

—none— 

199 

Module Start (BootRec* b) Word 

-none- 

199 

MsgBuffer data type 

—n/a— 

58 

MsgTag () MsgTag 

—none— 

48 

MsgTag (Msg& msg) MsgTag 

-none- 

49 

MsgTag data type 

-n/a- 

48 

Msg data type 

-n/a- 

49 
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page 

MyGloballd 0 Threadld 

—none— 

15 

MyGloballd () Threadld 

—none— 

17 

MyLocalld () Threadld 

-none- 

15 

MyLocalld () Threadld 

-none- 

17 

Myself () Threadld 

—none— 

15 

Myself () Threadld 

-none- 

17 

NaTPageMemory Word const 

-n/a- 

114 

Never Time const 

—n/a— 

28 

Next (BootRec* BootRec) BootRec* 

-none- 

197 

Nilpage Fpage const 

-n/a- 

37 

Niltag MsgTag const 

-n/a- 

48 

nilthread Threadld const 

-n/a- 

15 

NoAccess Word const 

—n/a— 

37 

NumMemoryDescriptors (void* Kernellnterface) Word 

-none- 

8 

NumProcessors (void* Kernellnterface) Word 

—none— 

8 

PageRights (void* Kernellnterface) Word 

—none— 

8 

Pager () Threadld 

-none- 

17 

Pager (Threadld t) Threadld 

ExchangeRegisters 

20 

PageSizeMask (void* Kernellnterface) Word 

-none- 

8 

PAL Call (Word idx, al, a2, a3, Word& rl, r2, r3) Word 

PAL.Call 

106 

PCIConflgFpageLog2 (Word BaseAddress, int Log2FpageSize < 64) Fpage 

—none— 

112 

PCIConflgFpage (Word BaseAddress, int FpageSize > 256) Fpage 

-none- 

112 

PreemptionPending () Bool 

—none— 

34 

ProcDesc (void* Kernellnterface, Word num) ProcDesc* 

—none— 

9 

ProcDesc data type 

—n/a— 

8 

ProcessorControl (Word ProcessorNo, control, IntemalFrequency, ExternalFre- 

—none— 

71 

quency, voltage) Word 



ProcessorNo () int 

—none— 

17 

Put (Msg& msg, Word 1, int u, Word& [m] ut, int t, {Maplterq Grantlterp Stringltem 

-none- 

49 

}& Items) void 



Put (Msg& msg. Word t, Grantltem g) void 

—none— 

50 

Put (Msg& msg. Word t, Mapltem m) void 

-none- 

49 

Put (Msg& msg. Word t, Stringltem& s) void 

-none- 

50 

Put (Msg& msg. Word t, Stringltem s) void 

-none- 

50 

Put (Msg& msg. Word u. Word w) void 

-none- 

49 

Rev Window (Acceptor a) Fpage 

—none— 

58 

Readable Word const 

—n/a— 

36 

ReadeXeeOnly Word const 

-n/a- 

37 

ReadPrecision (void* Kernellnterface) Word 

—none— 

9 

Receive (Threadld from) MsgTag 

Ipc 

64 

Receive (Threadld from, Time RcvTimeout) MsgTag 

Ipc 

64 

Reply Wait (Threadld to, Threadld& from) MsgTag 

IPC 

64 

ReplyWait (Threadld to. Time RcvTimeout, Threadld& from) MsgTag 

Ipc 

64 

Reply (Threadld to) MsgTag 

Ipc 

64 

ReservedMemoryType Word const 

-n/a- 

9 

Rights (Fpage f) Word 

-none- 

37 

SAL_Call (Word idx, al, a2, a3, a4, a5, a6. Word* rl, r2, r3) Word 

SAL.Call 

106 

SAI, PCI ConligRead (Word address, size, Word& value) Word 

SAL_Call 

106 

SAL_PCI_ConfigWrite (Word address, size, value) Word 

SAL.Call 

106 

SameThreads (Threadld 1, r) Bool 

ExchangeRegisters 

15 

SchedulePrecision (void* Kernellnterface) Word 

-none- 

9 

Schedule (Threadld dest, Word TimeControl, ProcessorControl, prio, Preemption- 

SCHEDULE 

33 

Control, Word& old_TimeControl) Word 



Send (Threadld to) MsgTag 

Ipc 

64 

Send (Threadld to. Time SndTimeout) MsgTag 

Ipc 

64 

Set CopFlag (Word n) void 

-none- 

17 

Set_CopFlag (Word n) void 

—none— 

69 

Set ExceptinnHandler (Threadld new) void 

—none— 

68 

Set_ExceptionHandler (Threadld NewHandler) void 

-none- 

17 

Set Label (Msg& msg, Word label) void 

—none— 

49 

Set_MsgTag (MsgTag t) void 

-none- 

48 

Set MsgTag (Msg& msg, MsgTag t) void 

—none— 

49 

Set_PageAttribute (Fpage f. Word attribute) Word 

MemoryControl 

73 
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page 

Set Pager (Threadld NewPager) void 

-none- 

17 

Set_Pager (Threadld t, p) void 

ExchangeRegisters 

20 

Set PagesAttributes (Word n, Fpage& [n] fpages, Word& [4] attributes) Word 

MemoryControl 

73 

Set_PreemptionDelay (Threadld dest. Word sensitivePrio, Word maxDelay) Word 

-none- 

33 

Set Priority (Threadld dest. Word prio) Word 

-none- 

33 

Set_ProcessorNo (Threadld dest. Word ProcessorNo) Word 

-none- 

33 

Set Propagation (Msg& Tag t) void 

—none— 

65 

Set_Rights (Fpage& f. Word AccessRights) void 

-none- 

37 

Set Timeslice (Threadld dest. Time ts. Time tq) Word 

-none- 

33 

Set_UserDeflnedHandle (Threadld t. Word handle) void 

ExchangeRegisters 

20 

Set UserDefinedHandle (Word NewValue) void 

-none- 

17 

Set_VirtualSender (Threadld t) void 

-none- 

17 

Set VirtualSender (Threadld t) void 

-none- 

65 

Set_XferTimeouts (Word NewValue) void 

-none- 

17 

SharedMemoryType Word const 

-n/a- 

9 

SimpleExec_BssPstart (BootRec* b) Word 

-none- 

199 

SimpleExec BssSi/e (BootRec* b) Word 

-none- 

200 

SimpleExec_BssVstart (BootRec* b) Word 

—none— 

199 

SimpleExec Cmdline (BootRec* b) char* 

-none- 

200 

SimpleExec_DataPstart (BootRec* b) Word 

—none— 

199 

SimpleExec DataSize (BootRec* b) Word 

-none- 

199 

SimpleExec_DataVstart (BootRec* b) Word 

-none- 

199 

SimpleExec Elags (BootRec* b) Word 

—none— 

200 

SimpleExecJnitiallP (BootRec* b) Word 

-none- 

200 

SimpleExec Eabel (BootRec* b) Word 

-none- 

200 

SimpleExec_Set_Flags (BootRec* b. Word w) void 

—none— 

200 

SimpleExec Set Label (BootRec* b. Word w) void 

-none- 

200 

SimpleExec_TextPstart (BootRec* b) Word 

—none— 

199 

SimpleExec_TextSize (BootRec* b) Word 

-none- 

199 

SimpleExec_TextVstart (BootRec* b) Word 

-none- 

199 

SizeLog2 (Fpage f) Word 

—none— 

37 

Size (Fpage f) Word 

-none- 

37 

Sleep (Time t) void 

Ipc 

64 

SmallSpace (Word location, size) Word 

-none- 

96 

SndBase (Grantltem g) Word 

-none- 

53 

SndBase (Mapltem m) Word 

—none— 

52 

SndFpage (Grantltem g) Fpage 

-none- 

53 

SndFpage (Mapltem m) Fpage 

-none- 

52 

SpaceControl (Threadld SpaceSpecifier, Word control, Fpage Kernellnter- 
facePageArea, UtcbArea, Threadld Redirector, Word& old_Control) Word 

SpaceControl 

43 

SpeculativeMemory Word const 

-n/a- 

124 

Start (Threadld t) void 

ExchangeRegisters 

21 

Start (Threadld t. Word sp, ip) void 

ExchangeRegisters 

21 

Start (Threadld t. Word sp, ip, flags) void 

ExchangeRegisters 

21 

Stop (Threadld t) ThreadState 

ExchangeRegisters 

21 

Stop (Threadld t, Word& sp, ip, flags) ThreadState 

ExchangeRegisters 

21 

StoreBRs (int i, k, Word& [A]) void 

—none— 

11 

StoreBRs (int i, k, Word& [A:]) void 

-none- 

58 

StoreBR (int i, Word& w) void 

-none- 

11 

StoreBR (int i, Word& w) void 

-none- 

58 

StoreMRs (int i, k, Word& [A] w ) void 

-none- 

11 

StoreMRs (int i, k, Word& [A] w ) void 

—none— 

50 

StoreMR (int i, Word& w) void 

-none- 

11 

StoreMR (int i, Word& w ) void 

-none- 

50 

Store (MsgTag t, Msg& msg) void 

—none— 

49 

StringltemsAcceptor Acceptor const 

-n/a- 

57 

Stringltems (Acceptor a) Bool 

-none- 

58 

Stringltem (int size, void* address) Stringltem 

-none- 

55 

Stringltem (Stringltem& s) Bool 

-none- 

55 

Stringltem data type 

-n/a- 

55 

Substrings (Stringltem& s) Word 

-none- 

55 

Substring (Stringltem& s. Word n) void* 

-none- 

55 

SystemClock () Clock 

SystemClock 

27 
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page 

ThreadControl (Threadld dest, SpaceSpecifier, Scheduler, Pager, void* UtcbLoca- 

ThreadControl 

24 

tion) Word 



ThreadldBits (void* Kernellnterface) Word 

-none- 

8 

ThreadldSystemBase (void* Kernellnterface) Word 

—none— 

8 

ThreadldUserBase (void* Kernellnterface) Word 

—none— 

9 

Threadld data type 

-n/a- 

15 

ThreadNo (Threadld t) Word 

—none— 

15 

ThreadState data type 

-n/a- 

21 

ThreadSwitch (Threadld dest) void 

ThreadSwitch 

30 

ThreadWasHalted (ThreadState s) Bool 

—none— 

21 

ThreadWasIpcing (ThreadState s) Bool 

-none- 

21 

ThreadWasReeeiving (ThreadState s) Bool 

-none- 

21 

ThreadWasSending (ThreadState s) Bool 

-none- 

21 

Timeouts (Time SndTimeout, RcvTimeout) Word 

-none- 

65 

TimePeriod (Word64 microseconds) Time 

—none— 

28 

TimePoint (Clock at) Time 

—none— 

29 

Timeslice (Threadld dest. Time & ts, Time & tq) Word 

-none- 

33 

Time data type 

-n/a- 

28 

TypedWords (Msg Tag t) Word 

-none— 

48 

Type (BootRec* BootRec) Word 

—none— 

197 

Type (MemoryDesc& m) Word 

—none— 

9 

UncacheableExportedMemory Word const 

-n/a- 

114 

UncacheableMemory Word const 

-n/a- 

114 

UncacheableMemory Word const 

-n/a- 

172 

UncacheableMemory Word const 

—n/a— 

98 

UndefinedMemoryType Word const 

-nJa- 

9 

Unmap (Fpage f) Fpage 

Unmap 

39 

Unmap (Word n, Fpage& [n] fpages) void 

Unmap 

39 

Unmap (Word control) void 

Unmap 

39 

UntypedWordsAcceptor Acceptor const 

-n/a- 

57 

UntypedWords (Msg Tag t) Word 

—none— 

48 

UseDefaultCacheUineAllocation CacheAllocationHint const 

-n/a- 

113 

UseDefaultCacheUineAllocation CacheAllocationHint const 

-n/a- 

171 

UseDefaultCacheUineAllocation CacheAllocationHint const 

-n/a- 

55 

UseDefaultCacheUineAllocation CacheAllocationHint const 

-n/a- 

97 

UserDefinedHandle () Word 

—none— 

17 

UserDefinedHandle (Threadld t) Word 

ExchangeRegisters 

20 

UtcbAlignmentUog2 (void* Kernellnterface) Word 

—none— 

9 

UtcbAreaSizeLog2 (void* Kernellnterface) Word 

—none— 

9 

UtcbSize (void* Kernellnterface) Word 

-none- 

9 

Version (Threadld t) Word 

—none— 

15 

Wait (Threadld& from) MsgTag 

Ipc 

64 

Wait (Time RcvTimeout, Threadld& from) MsgTag 

Ipc 

64 

WaseXecuted (Fpage f) Bool 

—none— 

40 

WasReferenced (Fpage f) Bool 

-none- 

40 

WasWritten (Fpage f) Bool 

-none- 

40 

Writable Word const 

-n/a- 

36 

WriteBackMemory Word const 

-n/a- 

114 

WriteBackMemory Word const 

-n/a- 

124 

WriteBackMemory Word const 

-n/a- 

172 

WriteBackMemory Word const 

-n/a- 

98 

WriteCoalescingMemory Word const 

-n/a- 

114 

WriteCombiningMemory Word const 

-n/a- 

172 

WriteCombiningMemory Word const 

-n/a- 

98 

WriteProtectedMemory Word const 

-n/a- 

172 

WriteProtectedMemory Word const 

-n/a- 

98 

WriteThroughMemory Word const 

-n/a- 

124 

WriteThroughMemory Word const 

-n/a- 

172 

WriteThroughMemory Word const 

-n/a- 

98 

XferTimeouts () Word 

—none— 

17 

Yield () void 

ThreadSwitch 

30 

ZeroTime Time const 

-n/a- 

28 
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!=, 15, 26, 29 
+, 26, 29, 37, 48, 56, 57 
+ =, 29, 37,48, 55-57 
-, 26, 29, 37, 57 
- (ignored), ix 
-=, 29, 37, 57 
<, 26, 29 
<=, 26, 29 
= (unchanged), ix 
==, 15, 26. 29, 48. 56 
>, 26, 29 
>=, 26, 29 
~ (undefined), ix 

(Jo, see sigmaO 

AbortIpc_and_stop , 21 
AbortReceivejmdstop, 21 
AbortSend-andstop , 2 1 
Accept , 58 
Accepted , 58 
acceptor, 57 
ACPIMemoryType , 115 
ActualSender, 17, 65 
Address , 37 
address space 

creation/deletion, 41 
initial, 81 

AllocateNewCacheLines , 97, 171 

AllocateOnlyNewLlCacheLines, 97, 171 

anylocal thread, 15 

any thread, 15 

ApiFlags , 8 

ApiVersion , 8 

Append, 49, 58 

ArchitectureSpecificMemoryType, 9 
Associatelnterrupt, 24 

Bootlnfo, 9 

BootInfo_EFITables, 199 
Bootlnfo .Entries, 197 
Bootlnfo -FirstEntry, 197 
Bootlnfo -Module, 199 
Bootlnfo -Multiboot, 199 
Bootlnfo SimpleExec, 199 
Bootlnfo Size, 197 
Bootlnfo -Valid, 197 
booting, 84-86 
alpha, 148 
amd64, 175 
arm, 194 
ia32, 101 
mips64, 160 
powerpc, 128 
ppc64, 140 

BootLoaderSpecificMemoiyType, 9 


BR, see buffer registers 
buffer registers, 57 
alpha, 143 
amd64, 163-164 
arm, 187 
ia32, 89-90 
ia64, 105 
mips64, 151 
powerpc, 119 
ppc64, 131 
sparc64, 179 

cacheability, 54, 97, 98, 113, 114, 124, 137. 157, 171, 
172, 191 

Cache AllocationHint, 56 
CacheNonTemporalAIILevels, 1 13 
CacheNonTemporalLl , 113 
CacheNonTemporalL2, 113 
CachingEnabledMemory, 124 
CachinglnhibitedMemory, 1 24 
Call, 63, 64 
Clear, 49, 58 
clock, 26 

reading, 27 
Clr _Cop Flag, 17, 69 
CompleteAddressSpace, 37 
CompundString, 55 

convenience programming interface, viii 
ConventionalMemoryType, 9 
coprocessors, 69 

Deassociatelnterrupt, 24 
debug registers, 100, 174 
DedicatedMemoryType, 9 
DefaultMemory, 73, 98, 114. 124, 172 
DisablePreemption, 34 
DisablePreemptionFaultException, 34 
DoNotAllocateNewCacheLines, 97, 171 

EFI_MemdescSize, 200 
EFl_MemdescVersion, 200 
EFI-Memmap, 200 
EFI_MemmapSize, 200 
EFISystab, 200 
EnablePreemption, 34 
EnablePreemptionFaultException, 34 
endian, 3 

ErrlnvalidParam, 33, 73 
ErrlnvalidScheduler, 24 
ErrlnvalidSpace, 24, 43 
ErrlnvalidThread, 21, 24, 33 
ErrKipArea, 43 
ErrNoMem, 24 

ErrNoPrivilege, 24, 33, 43, 71, 73 
ErrorCode, 17, 21, 24, 33, 43, 64, 71, 73 
ErrUtcbArea, 24, 43 
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exception 

handling, 68 
message 
amd64, 173 
arm, 193 
ia32, 99 
ia64, 116 
mips64, 158 
powerpc, 125 
ppc64, 138 
protocol, 80 

ExceptionHandler, 17, 68 
ExchangeRegisters, 20 
executable , 37 
ExternalFreq , 10 

Feature , 9 
Flush, 40 
Fpage, 37 
fpage, 36-37 

mapping, 59 
receiving, 57 
unmapping, 36, 38^-0 
FpageLog2, 37 
FullyAccessible, 37 

generic binary interface, viii 
generic bootinfo, 195-200 
data structure, 195-196 
generic record, 196-197 
generic programming interface, viii 
Get. 49, 50 
GetStatus, 40 
global thread ID, 14 
Globalld, 15, 20 
GlobalMemory, 124 
Grantltem , 53 
GuardedMemory, 124 

High , 9 

include files, x 
IntendedReceiver, 17, 64 
InternalFreq, 10 
interrupt 
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ppc64, 130-131 
sparc64, 178-179 
messages 

generating, 46-50 
model specific registers, 100, 174 
Module _Cmdline, 199 
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privileged threads, ix 
ProcDesc, 9 

processor-specific binary interface, viii 

Processor-Control , 71 

ProcessorNo, 16 

ProcessorNo, 17 

propagation, 60 

Put, 49, 50 

RcvWindow, 58 
RDMSR, 100, 174 
Readable , 36 
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ReservedMernoryType, 9 
Rights, 37 

SAL procedure calls, 106 
SALJCall, 106 
SALJPCUConfigRead, 106 
SAL PCI ConfigWrite, 106 
SameThreads, 15 
Schedule, 33 
SchedulePrecision, 9 
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SimpleExec JPextSize, 199 
SimpleExec JTextV start, 199 
Size, 37 
SizeLog2, 37 
Sleep, 64 
small spaces, 96 
SmallSpace, 96 
SndBase, 52, 53 
SndFpage, 52, 53 
SpaceControl, 43 
SpeculativeMemory, 124 
Start, 21 
Stop, 21 
Store, 49 
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